fix(voltage,docs,e2e): CodeRabbit review fixes + README badge restyle

CodeRabbit review on PR #29 surfaced two real bugs and four
quality-of-life issues. All addressed in one commit; piggy-backs the
unrelated README badge restyle (Federico-requested) since it's
trivial.

Bugs fixed:

1. **voltage.py: reject wrong-side transfer points before clamping.**
   A NUT driver reporting a high value (e.g., `input.transfer.low=250`)
   in the LOW transfer field passed the existing ±25% sanity check
   (|250-207|=43 ≤ 230×0.25=57.5) and produced `warning_low=255V` --
   making perfectly normal 230V mains read as a brownout on every
   poll. Symmetric bug on the high side (low value in high field
   would yield warning_high=195V, below the 207V low warning, an
   impossible band).

   Fix: low_transfer must be < nominal AND high_transfer must be >
   nominal before being accepted as a clamp candidate. Without the
   guard, the bogus value is silently ignored and we fall back to
   ±10%. Added regression tests covering 250/230V on the low side and
   200/230V on the high side, plus boundary cases (transfer == nominal
   is also rejected).

2. **voltage.py: don't claim EN 50160 accepts the UPS switch threshold.**
   The mild-event notification text said `UPS will not switch to
   battery until 280.0V (firmware setting); EN 50160 considers up to
   that level acceptable` -- which read as if EN 50160 sanctions 280V
   on a 230V grid. EN 50160 actually caps at nominal × 1.1 (253V),
   well below typical UPS switch points. The two are independent
   thresholds with different purposes.

   Fix: rewritten as `UPS will not switch to battery until 280.0V
   (firmware setting); this is a grid-quality issue (outside the
   EN 50160 ±10% envelope), not an imminent power loss.` -- accurate
   to the spec and applies symmetrically to high and low events.
   Updated the corresponding test_mild_overvoltage test to assert the
   new wording AND that the buggy phrasing must NOT appear.

Quality-of-life:

3. **docs/notifications.md, docs/triggers.md: "non-severe" instead
   of "10–15%".** With narrow UPS transfer points, the warning band
   can be tighter than ±10%, so non-severe events can fire at less
   than 10% deviation. The previous wording implied a fixed band.
4. **docs/triggers.md: replaced 122V-on-120V flap example.** 122V on
   a 120V grid is +1.7%, well within the normal band -- it would NOT
   trigger any warning, so it was a misleading example. Replaced with
   105V (12.5% under, past the ±10% warning threshold but not severe).
5. **docs/triggers.md: language hint on new fenced code blocks.**
   Added `text` to the log-output blocks for markdownlint MD040
   compliance. Existing yaml/shell blocks unchanged.
6. **tests/e2e/groups/single-ups.sh Test 6: tightened assertions.**
   The previous `grep -i "voltage\|brownout"` matched the startup
   `Voltage Monitoring Active` line, so a regression that broke
   BROWNOUT_DETECTED would still pass. Now requires the actual
   `BROWNOUT_DETECTED` event marker AND the rc9 `% below nominal`
   framing -- both as fail-closed `exit 1` instead of soft-warn.

README badge restyle (Federico-requested):

All 6 README badges switched to the dark/minimal `for-the-badge`
style with `labelColor=090909` and `color=e8e8ed` for visual
consistency. Codecov badge swapped from `codecov.io/...graph/badge.svg`
(no `for-the-badge` variant) to `img.shields.io/codecov/c/...` --
same data source, same link target, but now the style is honoured.
Codecov coverage % and PyPI version still display dynamically; only
their colour is overridden to keep the row uniform.

Tests: 747 -> 749 (+2 for the new transfer-side guards). All green.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

Author: m4r1k

README.md

@@ -4,12 +4,12 @@
 
 **UPS monitoring and shutdown orchestration for NUT**
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
-[![NUT Compatible](https://img.shields.io/badge/NUT-compatible-green.svg)](https://networkupstools.org/)
-[![codecov](https://codecov.io/gh/m4r1k/Eneru/branch/main/graph/badge.svg)](https://codecov.io/gh/m4r1k/Eneru)
-[![Documentation](https://img.shields.io/badge/docs-Read%20The%20Docs-blue.svg)](https://eneru.readthedocs.io/)
-[![PyPI](https://img.shields.io/pypi/v/eneru.svg)](https://pypi.org/project/eneru/)
+<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-e8e8ed?style=for-the-badge&labelColor=090909" alt="MIT"></a>
+<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.9+-e8e8ed?style=for-the-badge&labelColor=090909" alt="Python 3.9+"></a>
+<a href="https://networkupstools.org/"><img src="https://img.shields.io/badge/NUT-compatible-e8e8ed?style=for-the-badge&labelColor=090909" alt="NUT compatible"></a>
+<a href="https://codecov.io/gh/m4r1k/Eneru"><img src="https://img.shields.io/codecov/c/github/m4r1k/Eneru?style=for-the-badge&labelColor=090909&color=e8e8ed&label=Coverage" alt="Coverage"></a>
+<a href="https://eneru.readthedocs.io/"><img src="https://img.shields.io/badge/Docs-Read%20The%20Docs-e8e8ed?style=for-the-badge&labelColor=090909" alt="Documentation"></a>
+<a href="https://pypi.org/project/eneru/"><img src="https://img.shields.io/pypi/v/eneru?style=for-the-badge&labelColor=090909&color=e8e8ed&label=PyPI" alt="PyPI"></a>
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/m4r1k/Eneru/main/docs/images/eneru-diagram.svg" alt="Eneru Architecture" width="600">

docs/notifications.md

@@ -292,14 +292,18 @@ sqlite3 /var/lib/eneru/<UPS>.db \
 If the condition persists past the dwell, the notification fires
 with a `Persisted Ns.` annotation so you can see it was held.
 
-**Severity bypass (rc9, 5.1.0).** Mild deviations (10–15% from
-nominal) go through the dwell as described above. **Severe
-deviations** (greater than ±15% from nominal) bypass the dwell
-entirely and notify immediately, with a `(severe, X.X% below/above
-nominal)` tag and an `Approaching UPS battery-switch threshold`
-callout when NUT exposes the UPS's transfer points. The reasoning:
-- Mild deviations are usually flap from neighbour appliances cycling
-  — the 30s filter is the right call.
+**Severity bypass (rc9, 5.1.0).** Non-severe voltage warnings (up
+to and including ±15% from nominal) go through the dwell as
+described above. **Severe deviations** (greater than ±15% from
+nominal) bypass the dwell entirely and notify immediately, with a
+`(severe, X.X% below/above nominal)` tag and an
+`Approaching UPS battery-switch threshold` callout when NUT
+exposes the UPS's transfer points. The reasoning:
+- Non-severe events are usually flap from neighbour appliances
+  cycling — the 30s filter is the right call. Note that with
+  narrow UPS transfer points the warning thresholds may be tighter
+  than ±10%, so the "non-severe" band can fire at less than 10%
+  deviation; the dwell still applies.
 - Severe deviations indicate real grid trouble (utility fault,
   generator instability, site wiring issue) — the operator wants
   to know immediately, not 30s later.

docs/triggers.md

@@ -82,11 +82,14 @@ What Eneru does instead:
    `OVER_VOLTAGE_DETECTED` / `BROWNOUT_DETECTED` is always written
    immediately on transition. The *notification* dispatch is gated by
    severity:
-   - **Mild deviations** (10–15% from nominal) go through
-     `notifications.voltage_hysteresis_seconds` (default 30s). A
-     2-second flap to 122V on a 120V grid no longer pages you; a
-     sustained event still does — and arrives with a
-     `Persisted Ns.` annotation.
+   - **Non-severe voltage warnings** (up to and including ±15% from
+     nominal) go through `notifications.voltage_hysteresis_seconds`
+     (default 30s). A 2-second flap to 105V on a 120V grid (12.5%
+     under nominal — past the warning threshold but not severe) no
+     longer pages you; a sustained event still does, and arrives
+     with a `Persisted Ns.` annotation. With narrow UPS transfer
+     points the warning band can be tighter than ±10%, so non-severe
+     events can fire at less than 10% deviation.
    - **Severe deviations** (`>±15%` from nominal) bypass the dwell
      and notify **immediately** with a `(severe, X.X% below/above
      nominal)` tag. These signal real grid trouble — utility fault,
@@ -105,7 +108,7 @@ What Eneru does instead:
 
 ### What you'll see in the log
 
-```
+```text
 📊 Voltage Monitoring Active.
    Nominal: 230.0V (NUT=230.0).
    Grid-quality warnings: 207.0V / 253.0V (±10% nominal, EN 50160 envelope).
@@ -122,16 +125,17 @@ information, not an active power event).
 
 **Mild brownout (UPS won't switch):**
 
-```
+```text
 🔻 BROWNOUT_DETECTED: input voltage 200.0V is 13.0% below 230V nominal
    (warning threshold 207.0V). Persisted 30s.
    UPS will not switch to battery until 170.0V (firmware setting);
-   this is a grid-quality issue, not an imminent power loss.
+   this is a grid-quality issue (outside the EN 50160 ±10% envelope),
+   not an imminent power loss.
 ```
 
 **Severe brownout (UPS may switch shortly):**
 
-```
+```text
 🔻 BROWNOUT_DETECTED: (severe, 21.7% below nominal): input voltage 180.0V.
    Notifying immediately (bypassed hysteresis).
    Approaching UPS battery-switch threshold (170.0V) -- battery may

src/eneru/health/voltage.py

@@ -61,28 +61,44 @@ def _derive_warning_low(nominal: float, low_transfer) -> float:
     """Pick the warning-low threshold: the *tighter* (higher) of ±10% and (transfer + buffer).
 
     Tighter = warns earlier = better grid-quality signal. NUT's
-    transfer point is honored only when it's plausibly close to the
-    expected ±10% line (within ±25%); a wildly mis-reported transfer
-    value is ignored so we always have at least the ±10% safety net.
+    transfer point is honored only when:
+      - it's numeric,
+      - it's BELOW the nominal (a low-transfer at or above nominal is
+        nonsense -- means the UPS would switch on perfectly normal mains),
+      - and it's within ±25% of the expected ±10% line.
+
+    The "below nominal" guard catches the bug where a NUT driver
+    reports a high value (e.g., 250 on a 230V grid) in the low-transfer
+    field; without the guard we'd compute warning_low = 255V and then
+    230V mains would falsely fire BROWNOUT_DETECTED. With the guard
+    the bogus value is ignored and we fall back to ±10%.
+
     Rounded to one decimal so the log line and notification text stay
     clean (avoids 253.00000000000003 from float multiplication).
     """
     pct_band = nominal * (1 - GRID_QUALITY_DEVIATION_PCT)
     candidates = [pct_band]
     if is_numeric(low_transfer):
         lt = float(low_transfer)
-        if abs(lt - pct_band) <= nominal * 0.25:
+        if lt < nominal and abs(lt - pct_band) <= nominal * 0.25:
             candidates.append(lt + TRANSFER_BUFFER_V)
     return round(max(candidates), 1)
 
 
 def _derive_warning_high(nominal: float, high_transfer) -> float:
-    """Pick the warning-high threshold: the *tighter* (lower) of ±10% and (transfer - buffer)."""
+    """Pick the warning-high threshold: the *tighter* (lower) of ±10% and (transfer - buffer).
+
+    Symmetric guard to ``_derive_warning_low``: high transfer must be
+    ABOVE nominal to be plausible. A NUT driver reporting 200 on a 230V
+    grid in the high-transfer field would otherwise compute a warning
+    of 195V, well below the 207V ±10% threshold -- forcing the warning
+    band wider rather than tighter, which defeats the whole clamp.
+    """
     pct_band = nominal * (1 + GRID_QUALITY_DEVIATION_PCT)
     candidates = [pct_band]
     if is_numeric(high_transfer):
         ht = float(high_transfer)
-        if abs(ht - pct_band) <= nominal * 0.25:
+        if ht > nominal and abs(ht - pct_band) <= nominal * 0.25:
             candidates.append(ht - TRANSFER_BUFFER_V)
     return round(min(candidates), 1)
 
@@ -337,22 +353,21 @@ def _format_voltage_detail(self, direction: str, voltage: float,
         # transfer point. For severe events, frame as "battery may
         # engage shortly"; for mild, frame as "this is a grid quality
         # issue, not an imminent power loss".
+        # NOTE: do NOT imply EN 50160 considers the UPS switch point
+        # acceptable. EN 50160 caps at nominal × 1.1 (e.g., 253V on
+        # 230V), well below typical UPS switch points (e.g., 280V).
+        # The two are independent thresholds with different purposes.
         ups_switch = (self.state.ups_transfer_low if direction == "low"
                       else self.state.ups_transfer_high)
         if ups_switch is not None:
             if is_severe:
                 tail = (f"Approaching UPS battery-switch threshold "
                         f"({ups_switch}V) -- battery may engage shortly.")
             else:
-                en50160_note = (
-                    "EN 50160 considers up to that level acceptable; "
-                    if direction == "high" else ""
-                )
                 tail = (f"UPS will not switch to battery until "
-                        f"{ups_switch}V (firmware setting); "
-                        f"{en50160_note}"
-                        f"this is a grid-quality issue, not an "
-                        f"imminent power loss.")
+                        f"{ups_switch}V (firmware setting); this is "
+                        f"a grid-quality issue (outside the EN 50160 "
+                        f"±10% envelope), not an imminent power loss.")
         else:
             tail = ""
 

tests/e2e/groups/single-ups.sh

@@ -173,11 +173,15 @@ sleep 2
 # Run briefly to detect brownout
 timeout 8 eneru run --config $E2E_DIR/config-e2e-dry-run.yaml 2>&1 | tee /tmp/test6.log || true
 
-# Verify brownout was detected (should log a voltage warning)
-if grep -q -i "voltage\|brownout" /tmp/test6.log; then
-  echo "PASS (6a): Voltage event detected"
+# Verify brownout was specifically detected -- not just any voltage
+# log line. The startup `Voltage Monitoring Active` line would match
+# `voltage` and let a regression slip through; require the actual
+# BROWNOUT_DETECTED event marker.
+if grep -q "BROWNOUT_DETECTED" /tmp/test6.log; then
+  echo "PASS (6a): BROWNOUT_DETECTED event fired"
 else
-  echo "Note: Voltage event may not have been logged in short window"
+  echo "FAIL (6a): brownout scenario did not produce BROWNOUT_DETECTED log"
+  exit 1
 fi
 
 # rc9: startup log line should expose BOTH the grid-quality warning
@@ -204,11 +208,12 @@ fi
 # rc9: the BROWNOUT detail must include the % deviation framing.
 # Notification dispatch is gated by hysteresis (default 30s) so it
 # may not fire in our 8s window, but the immediate BROWNOUT_DETECTED
-# log row carries the same detail string.
+# log row carries the same detail string -- so this MUST be present.
 if grep -q "below.*nominal" /tmp/test6.log; then
   echo "PASS (6d): brownout log carries 'below nominal' framing"
 else
-  echo "Note (6d): 'below nominal' framing absent in test window"
+  echo "FAIL (6d): brownout log missing rc9 '<X>% below <Y>V nominal' framing"
+  exit 1
 fi
 )
 

tests/test_voltage.py

@@ -370,6 +370,26 @@ def test_garbage_transfer_falls_back_to_ten_percent(self):
         assert _derive_warning_low(120, 250) == 108.0   # 250 way off |250-108|=142 > 30
         assert _derive_warning_high(120, 50) == 132.0   # 50 way off |50-132|=82 > 30
 
+    @pytest.mark.unit
+    def test_low_transfer_at_or_above_nominal_is_rejected(self):
+        # Regression for CodeRabbit major: NUT reporting low_transfer
+        # >= nominal is nonsense (UPS would switch on perfectly normal
+        # mains). Without the guard, low_transfer=250 on 230V passes
+        # the ±25% sanity (|250-207|=43 ≤ 57.5) and would yield
+        # warning_low=255, making 230V mains read as a brownout.
+        assert _derive_warning_low(230, 250) == 207.0   # rejected, fall back to ±10%
+        assert _derive_warning_low(230, 230) == 207.0   # equal also rejected
+        assert _derive_warning_low(230, 231) == 207.0   # just-above also rejected
+
+    @pytest.mark.unit
+    def test_high_transfer_at_or_below_nominal_is_rejected(self):
+        # Symmetric guard: high_transfer <= nominal is nonsense.
+        # 200 on 230V would otherwise yield warning_high = 195V,
+        # below the 207V low warning -- impossible band.
+        assert _derive_warning_high(230, 200) == 253.0   # rejected
+        assert _derive_warning_high(230, 230) == 253.0   # equal also rejected
+        assert _derive_warning_high(230, 229) == 253.0   # just-below also rejected
+
     @pytest.mark.unit
     def test_state_records_ups_transfer_points(self):
         h = _TestHost(ups_vars={
@@ -564,13 +584,23 @@ def test_message_omits_ups_context_when_transfer_unknown(self):
         assert "13.0% below" in body
 
     @pytest.mark.unit
-    def test_mild_overvoltage_includes_en50160_hint(self):
+    def test_mild_overvoltage_explains_en50160_envelope_correctly(self):
+        # Regression for CodeRabbit major: the previous "EN 50160
+        # considers up to that level acceptable" wording was wrong --
+        # it implied EN 50160 accepts the UPS switch threshold (e.g.,
+        # 280V), but EN 50160 actually caps at nominal × 1.1 (253V on
+        # 230V). The corrected message frames the warning as outside
+        # the EN 50160 ±10% envelope without putting words into the
+        # standard's mouth about higher voltages.
         h = _TestHost(ups_vars={
             "input.voltage.nominal": "230",
             "input.transfer.high": "280",
         }, hysteresis=0)
         h._initialize_voltage_thresholds()
         h._check_voltage_issues("OL", "256")  # 11.3% above, mild
         body, _ = h.notifications[0]
-        assert "EN 50160 considers up to that level acceptable" in body
+        # Corrected wording: warning is OUTSIDE the EN 50160 envelope.
+        assert "outside the EN 50160" in body
         assert "UPS will not switch to battery until 280.0V" in body
+        # The buggy wording must NOT appear.
+        assert "EN 50160 considers up to that level acceptable" not in body