diff --git a/opencode/decisions.yaml b/opencode/decisions.yaml
index 7462fbea..39b9f26c 100644
--- a/opencode/decisions.yaml
+++ b/opencode/decisions.yaml
@@ -622,3 +622,24 @@ notes:
       - zigbee2mqtt
     pin: true
     status: superseded
+  - id: 2026-08-28-filter-plug-hardware-faulty-matter-swap
+    date: 2026-08-28
+    title: Filter plug hardware-faulty; Matter swap uses switch.filter name
+    decision: "Filter plug (0xffffb40e060893d8) is hardware-faulty (0xe1 downlink; do not
+      re-diagnose). Replace with Kasa KP125M Matter plugs. Plan: delete old plug to free
+      switch.filter, commission Kasa, rename entity to switch.filter so automations keep
+      working; rework health-alert."
+    rationale: Consolidates the hardware-fault finding with the decided setup approach,
+      superseding the earlier "re-point references" note which is now wrong for the
+      switch. Renaming the new Matter entity to switch.filter requires removing the old
+      plug first (entity ID collision). Health-alert automation must be reworked because
+      the Zigbee linkquality sensor disappears with the old plug; printer automation and
+      dashboard tile keep working via the renamed entity.
+    entities:
+      - switch.filter
+      - sensor.0xffffb40e060893d8_linkquality
+    integrations:
+      - matter
+      - zigbee2mqtt
+    pin: true
+    status: active