HomeAssistantVS/opencode/decisions.yaml

# OpenCode decision notes
#
# Decisions and constraints about this Home Assistant installation, recorded by
# the OpenCode add-on only when you approve them. OpenCode reads a short digest
# of the active notes at the start of every session.
#
# Safe to edit or delete by hand. Keep the shape below; OpenCode refuses to add
# notes while the file cannot be parsed, so nothing is silently overwritten.
#
# Set a note's status to "superseded" (or delete it) to drop it from the digest.
# Add "pin: true" to a note to keep it in the digest when older notes no longer
# fit — use it for the decisions that must never be reversed by accident.

version: 1
notes:
  - id: 2026-07-29-nest-snapshot-custom-integration
    date: 2026-07-29
    title: nest_snapshot custom integration abandoned
    decision: nest_snapshot integration is abandoned. WebRTC SDP parsing was fixed but ICE
      connection to Google Nest's ice-lite candidates never establishes (30s timeout). Do
      not revisit.
    rationale: After resolving SDP candidate format issues (missing component-id), aiortc
      could parse Google's answer but ICE connectivity checks timed out every time across
      multiple restarts. Track handler fires but recv() never gets a frame. Root cause
      undetermined — likely aiortc STUN connectivity or ice-lite compatibility issue. Not
      worth further effort.
    files:
      - custom_components/nest_snapshot/__init__.py
      - custom_components/nest_snapshot/manifest.json
      - custom_components/nest_snapshot/services.yaml
    integrations:
      - nest_snapshot
    pin: true
    status: superseded
    superseded_by: 2026-09-06-nest-snapshot-custom-integration
  - id: 2026-08-06-octoprint-automation-playroom-light
    date: 2026-08-06
    title: OctoPrint automation (playroom light + basement heat) pending — via MQTT/OctoMQTT
    decision: "Built-in OctoPrint integration is broken here (AssertionError device_id is not
      None; no printer entities). Chosen route: OctoMQTT plugin, trigger on
      octoPrint/event/PrintStarted. Pending automation: when print starts, turn on
      light.playroom_light and set climate.basement to 22C."
    rationale: Completed the built-in OctoPrint integration setup flow but HA logs show setup
      errors for sensor/binary_sensor/button/camera/number platforms, so there is nothing
      to trigger on. User chose the MQTT route and will configure the OctoMQTT plugin
      later (printer is currently busy). Leave the broken OctoPrint entry alone until this
      is resolved.
    entities:
      - light.playroom_light
      - climate.basement
    integrations:
      - octoprint
      - mqtt
    status: superseded
    superseded_by: 2026-08-06-3d-printer-automation-runs-on-helper
  - id: 2026-08-06-3d-printer-automation-runs-on-helper
    date: 2026-08-06
    title: 3D printer automation runs on helper, not MQTT
    decision: "When the OctoPrint HA plugin toggles input_boolean.3d_printer_running: ON ->
      playroom + bedroom lamps on, basement 22C heat; OFF -> playroom light off after 10
      min, thermostat untouched. Mode restart cancels pending off on a new print. Old MQTT
      automation stays disabled."
    rationale: Built-in OctoPrint integration is broken here (AssertionError device_id is not
      None; no printer entities). The OctoMQTT event trigger was replaced by a
      helper-based design so OctoPrint can toggle a HA entity directly (plugin pointed at
      the helper) and print-end handling (delayed light off) becomes possible. Built,
      tested, and working 2026-08-06.
    entities:
      - input_boolean.3d_printer_running
      - light.playroom_light
      - light.bedroom_lamp
      - climate.basement
    integrations:
      - octoprint
      - mqtt
    status: active
  - id: 2026-08-06-octomqtt-still-enabled-for-future
    date: 2026-08-06
    title: OctoMQTT still enabled for future automations
    decision: OctoMQTT plugin remains enabled on the OctoPrint side and keeps publishing to
      octoPrint/event/... topics. The current print-start automation uses the
      input_boolean helper, but this MQTT stream stays available for future, more complex
      automations (print progress, job done, errors, etc.).
    rationale: The helper-based automation only covers start/end. Keeping OctoMQTT running
      preserves richer OctoPrint events for later automation without reconfiguring the
      printer. No conflict with the helper automation — they are complementary.
    integrations:
      - octoprint
      - mqtt
    status: active
  - id: 2026-08-07-printer-totals-history-stats-via-config
    date: 2026-08-07
    title: "Printer totals: history_stats via config flow (HA 2026.8: no YAML)"
    decision: Print totals (print time + counts, today/week/7d) are history_stats config-flow
      helpers (sensor.octoprint_printer_*), shown in the Totals section of the
      printer-stats/print dashboard. history_stats no longer supports YAML in HA 2026.8 —
      create helpers via config flow/UI only, never a configuration.yaml entry.
    rationale: Session paused 2026-08-06 to continue later. YAML history_stats was rejected by
      core with "history_stats does not support YAML setup", so all six sensors were
      created via config flow and verified live; the Totals dashboard section is committed
      (config hash 57e4ba20d169bbf3, render path printer-stats/print). Config-flow helpers
      need no restart.
    entities:
      - sensor.octoprint_printer_print_time_today
      - sensor.octoprint_printer_print_time_this_week
      - sensor.octoprint_printer_print_time_last_7_days
      - sensor.octoprint_printer_prints_today
      - sensor.octoprint_printer_prints_this_week
      - sensor.octoprint_printer_prints_last_7_days
    integrations:
      - history_stats
      - octoprint
      - mqtt
    status: active
  - id: 2026-08-07-octoprint-controls-are-mqtt-via
    date: 2026-08-07
    title: OctoPrint controls are MQTT via OctoMQTT plugin
    decision: OctoPrint controls are MQTT entities from the installed OctoMQTT/Discovery
      plugin v3.7.0, publishing to octoPrint/hassControl/*. Cancel/pause show unavailable
      while idle by design (availability tied to octoPrint/hass/is_printing). No native
      octoprint integration needed.
    rationale: "Verified via mqtt/device/debug_info on device
      9b0fd332d68cc7010c998450c00d49f2: each entity carries a command_topic on
      octoPrint/hassControl/* (cancel, pause, stop, camera_snapshot, connect) that the
      plugin subscribes to inside OctoPrint. The command path was proven working - a
      camera_snapshot toggle earlier today transmitted True to the broker. Commands are
      fire-and-forget; confirm landing by watching sensor.octoprint_print_status."
    entities:
      - button.octoprint_cancel_print
      - switch.octoprint_pause_print
      - switch.octoprint_camera_snapshot
      - switch.octoprint_connect_to_printer
    integrations:
      - mqtt
      - octoprint
    status: active
  - id: 2026-08-07-octoprint-frozen-sensors-shown-via-idle
    date: 2026-08-07
    title: OctoPrint frozen sensors shown via idle-zero template helpers
    decision: OctoPrint sensors freeze at last-print values when idle. The /printer-stats
      dashboard uses template helpers (sensor.octoprint_elapsed,
      sensor.octoprint_time_left, sensor.octoprint_current_z_2) reporting 0 while printing
      is off. Keep cards on helpers; raw sensors stay intact.
    rationale: "While idle the raw sensors freeze at end-of-print values (elapsed 6661s,
      current Z 26.8mm), looking like a mid-print and producing stale charts. Helper
      template: {{ 0 if not is_state('binary_sensor.octoprint_printing','on') else
      states('<source>')|float }}. The Current Z helper got _2 suffix because its friendly
      name collided with the raw sensor's slug."
    entities:
      - sensor.octoprint_elapsed
      - sensor.octoprint_time_left
      - sensor.octoprint_current_z_2
      - binary_sensor.octoprint_printing
      - sensor.octoprint_print_time
      - sensor.octoprint_print_time_left
      - sensor.octoprint_current_z
    integrations:
      - octoprint
      - template
    status: superseded
    superseded_by: 2026-08-07-octoprint-frozen-sensors-shown-via-idle-2
  - id: 2026-08-07-octoprint-frozen-sensors-shown-via-idle-2
    date: 2026-08-07
    title: OctoPrint frozen sensors shown via idle-zero template helpers
    decision: "OctoPrint duration sensors freeze when idle. The /printer-stats dashboard uses
      template helpers (sensor.octoprint_elapsed, sensor.octoprint_time_left) reporting 0
      while printing is off. Current Z stays on the raw sensor: the nozzle physically
      remains at its height when idle."
    rationale: "Elapsed and time-left are durations tied to a running print, so 0 while idle
      is correct. Current Z is a physical position that persists — zeroing it would
      falsely claim the nozzle is at the build plate. Helper template: {{ 0 if not
      is_state('binary_sensor.octoprint_printing','on') else states('<source>')|float }}.
      An earlier Z helper (octoprint_current_z_2) was created then deleted after this
      distinction was realized."
    entities:
      - sensor.octoprint_elapsed
      - sensor.octoprint_time_left
      - binary_sensor.octoprint_printing
      - sensor.octoprint_print_time
      - sensor.octoprint_print_time_left
      - sensor.octoprint_current_z
    integrations:
      - octoprint
      - template
    status: active
  - id: 2026-08-07-octoprint-camera-go2rtc-h264-transcode
    date: 2026-08-07
    title: "OctoPrint camera: go2rtc H264 transcode required for WebRTC"
    decision: Ender camera (endercamera.duckdns.org) streams MJPEG only; go2rtc serves it
      transcoded to H264 (ffmpeg:...#video=h264) because WebRTC cannot negotiate MJPEG.
      Keep this transcode. The printer-stats dashboard webrtc card uses go2rtc's named
      'octoprint' stream, never a raw URL.
    rationale: "Fixed the webrtc-camera card's DESCRIBE error (dead
      rtsp://127.0.0.1:18554/octoprint) and 'codec not matched' error (MJPEG over WebRTC).
      Operational trap discovered: do NOT POST to go2rtc /api/config - it persists its
      JSON body into go2rtc.yaml, silently overwriting config. To change streams, edit
      /homeassistant/go2rtc.yaml and reload the webrtc integration (entry
      01KWT295KFJ9V0N6ZXG88JM3GA); the embedded go2rtc reads that file on reload."
    entities:
      - camera.endercamera_duckdns_org
    files:
      - go2rtc.yaml
    integrations:
      - webrtc
      - octoprint
    pin: true
    status: active
  - id: 2026-08-08-printjobhistory-external-db-settings
    date: 2026-08-08
    title: PrintJobHistory external-DB settings are inert defaults
    decision: The PrintJobHistory plugin's datbaseSettings (useExternal=true, type=postgres,
      user=Olli, etc.) are hardcoded defaults in get_settings_defaults(), never read by
      plugin code. The plugin always uses a local SQLite DB in its plugin data folder. Do
      not set up Postgres.
    rationale: "Confirmed from OllisGit/OctoPrint-PrintJobHistory source: 'useExternal'
      appears only in the defaults dict; DatabaseManager.py uses sqlite3.connect()
      exclusively; the lone 'postgres' string is in testConnection(), invoked only from
      the settings-UI test button. The API already serves valid JSON from SQLite
      (totalItemCount=0) proving the store works."
    entities:
      - sensor.octoprint_filament_used_total
      - sensor.octoprint_last_print_filament
    files:
      - configuration.yaml
    integrations:
      - octoprint
    status: active
  - id: 2026-08-08-midea-dishwasher-has-dhcp-reservation
    date: 2026-08-08
    title: Midea dishwasher has DHCP reservation
    decision: The Midea dishwasher (MAC c0:88:40:53:27:7c) has a DHCP reservation at
      192.168.1.84. The midea_ac_lan "Dishwasher" config entry must keep this IP; if
      entities go unavailable, verify the IP before anything else.
    rationale: On 2026-08-08 the dishwasher dropped offline at the old IP (192.168.1.83) after
      a DHCP lease change; it moved to .84 and the reservation was added to prevent
      recurrence.
    entities:
      - binary_sensor.150633095332665_door
    integrations:
      - midea_ac_lan
    status: active
  - id: 2026-08-14-octoprint-progress-never-reinstall-m73
    date: 2026-08-14
    title: "OctoPrint progress: never reinstall M73-injecting plugins"
    decision: Never reinstall M73-injecting OctoPrint plugins (old "M73 plugin", Detailed
      Progress with use_M73). They inject M73 P0 which overrides file-position progress
      via serial.trustM73, freezing completion at 0%. If LCD M73 progress is wanted later,
      set plugins.serial_connector.trustM73=false and keep the plugin.
    rationale: "Diagnosed 2026-08-14: progress froze at 0% while /api/job filepos reached
      100%. OctoPrint 2.0.0rc4 adopts any streamed M73 P value as authoritative progress
      once trustM73 is true; the file had no M73 lines, so P0 came from plugin injection
      and was never updated (file uses M117 DASHBOARD_LAYER_INDICATOR, not ;LAYER:
      comments). Uninstalling the plugins restored correct progress immediately."
    entities:
      - sensor.octoprint_print_progress
      - sensor.octoprint_print_status
      - binary_sensor.octoprint_printing
    integrations:
      - octoprint
    pin: true
    status: active
  - id: 2026-08-14-octoprint-live-rest-sensors-are-the
    date: 2026-08-14
    title: "OctoPrint: `_live` REST sensors are the accurate source, MQTT push lags"
    decision: OctoPrint MQTT push progress events are throttled (~5-13 min gaps), so MQTT
      sensors lag. The `_live` REST sensors (/api/job every 30s) are the accurate source.
      Keep dashboards and helpers on `_live` sensors; do not swap MQTT sensors back in for
      display.
    rationale: "2026-08-14: throttled PrintProgress push left MQTT sensor.octoprint_print_time
      ~18 min stale vs live REST. Switched sensor.octoprint_elapsed helper to live REST
      printTime attribute and History graph to sensor.octoprint_print_progress_live.
      Rounded progress to 2 decimals so slow prints visibly advance (2.4 -> 2.45). Elapsed
      2611s matched wall-clock printTime exactly."
    entities:
      - sensor.octoprint_print_progress_live
      - sensor.octoprint_print_time_left_live
      - sensor.octoprint_print_state_live
      - sensor.octoprint_elapsed
      - sensor.octoprint_print_progress
      - sensor.octoprint_print_time
    files:
      - configuration.yaml
    integrations:
      - octoprint
      - rest
      - mqtt
      - template
    status: superseded
    superseded_by: 2026-08-14-octoprint-live-rest-sensors-are-the-2
  - id: 2026-08-14-octoprint-live-rest-sensors-are-the-2
    date: 2026-08-14
    title: "OctoPrint: `_live` REST sensors are the accurate source, MQTT push lags"
    decision: OctoPrint MQTT push progress events are throttled (~5-13 min gaps), so MQTT
      sensors lag. The `_live` REST sensors (/api/job every 30s) are the accurate source.
      Keep dashboards and helpers on `_live` sensors; do not swap MQTT sensors back in for
      display.
    rationale: "2026-08-14: throttled PrintProgress push left MQTT sensor.octoprint_print_time
      ~18 min stale vs live REST. Switched sensor.octoprint_elapsed helper to live REST
      printTime attribute and History graph to sensor.octoprint_print_progress_live.
      Rounded progress to 2 decimals so slow prints visibly advance (2.4 -> 2.45). Elapsed
      2611s matched wall-clock printTime exactly."
    entities:
      - sensor.octoprint_print_progress_live
      - sensor.octoprint_print_time_left_live
      - sensor.octoprint_print_state_live
      - sensor.octoprint_elapsed
      - sensor.octoprint_print_progress
      - sensor.octoprint_print_time
    files:
      - configuration.yaml
    integrations:
      - octoprint
      - rest
      - mqtt
      - template
    pin: true
    status: active
  - id: 2026-08-14-octoprint-printjobhistory-set-to
    date: 2026-08-14
    title: OctoPrint PrintJobHistory set to capture all jobs (not just successful)
    decision: OctoPrint's PrintJobHistory plugin is set to capture ALL jobs (success +
      failed/cancelled), not "success jobs only". Failed/cancelled prints are now recorded
      so their filament usage flows into sensor.octoprint_filament_used_total and the
      daily/weekly/monthly filament meters. Do not revert to success-only.
    rationale: With "capture successful jobs only", cancelled/failed prints (e.g. 2026-08-14
      11:09 and 16:32) never entered OctoPrint's history, so no filament usage reached HA
      at all — the gap was OctoPrint-side, not an HA integration issue.
      Sensor.octoprint_filament_used_total only updates on prints OctoPrint records.
    entities:
      - sensor.octoprint_filament_used_total
      - sensor.octoprint_filament_daily
      - sensor.octoprint_filament_weekly
      - sensor.octoprint_filament_monthly
    integrations:
      - octoprint
    status: superseded
    superseded_by: 2026-08-14-octoprint-printjobhistory-set-to-2
  - id: 2026-08-14-octoprint-printjobhistory-set-to-2
    date: 2026-08-14
    title: OctoPrint PrintJobHistory set to capture all jobs (not just successful)
    decision: OctoPrint's PrintJobHistory plugin is set to capture ALL jobs (success +
      failed/cancelled), not "success jobs only". Failed/cancelled prints are now recorded
      so their filament usage flows into sensor.octoprint_filament_used_total and the
      daily/weekly/monthly filament meters. Do not revert to success-only.
    rationale: With "capture successful jobs only", cancelled/failed prints (e.g. 2026-08-14
      11:09 and 16:32) never entered OctoPrint's history, so no filament usage reached HA
      at all — the gap was OctoPrint-side, not an HA integration issue.
      Sensor.octoprint_filament_used_total only updates on prints OctoPrint records.
    entities:
      - sensor.octoprint_filament_used_total
      - sensor.octoprint_filament_daily
      - sensor.octoprint_filament_weekly
      - sensor.octoprint_filament_monthly
    integrations:
      - octoprint
    pin: true
    status: active
  - id: 2026-08-16-matter-outage-2026-08-16-was-thread
    date: 2026-08-16
    title: Matter outage 2026-08-16 was Thread mesh re-forming, not host firewall
    decision: The 2026-08-16 Matter node outages were traced to the external Thread border
      router's mesh re-forming (mesh prefix rotated fdfb:c653:60c7 → fd25:f6c0:5149). NOT
      a host routing/firewall issue. Devices self-heal once the matter server re-learns
      the new operational addresses; a per-device forced reconnect accelerates it.
    rationale: "Evidence: all 7 nodes rotated to the new fd25 prefix between 03:28–03:36; the
      host routed live Matter traffic fine throughout (office button session, scroll-wheel
      button events); Thread integration shows 0 border routers and no OTBR add-on exists,
      so routing depends on an external border router. Do not chase firewall/iptables
      theories for this failure signature."
    integrations:
      - matter
      - thread
    status: active
  - id: 2026-08-21-octoprint-serial-health-sensors-removed
    date: 2026-08-21
    title: OctoPrint serial-health sensors removed deliberately
    decision: sensor.octoprint_serial_health_ratio and
      binary_sensor.octoprint_serial_health_critical are removed from configuration.yaml
      and both dashboards. Do not re-add them.
    rationale: OctoPrint-MQTT never publishes a printer_data.health object, so
      value_json.printer_data.health.ratio/.critical fell back to float(0)/OFF forever —
      the tiles always read 0%. No equivalent real data exists (only web-service stats).
      Removed from printer-stats + ender5-printer dashboards, YAML source deleted,
      mqtt.reload applied, registry stubs cleaned.
    entities:
      - sensor.octoprint_serial_health_ratio
      - binary_sensor.octoprint_serial_health_critical
    files:
      - configuration.yaml
    integrations:
      - mqtt
    status: active
  - id: 2026-08-23-enp1s0-ipv6-static-no-gateway
    date: 2026-08-23
    title: enp1s0 IPv6 static-no-gateway workaround (Bell router v6 black-hole)
    decision: "enp1s0 IPv6 deliberately Static, NO gateway: v6 internet fails fast, apps fall
      back to IPv4. Set 2026-08-23 after Bell router's v6 route black-holed connections
      (Tuya died). User does NOT need IPv6 beyond Matter link-local — keep this setup
      permanently. Never disable IPv6 fully — Matter needs link-local."
    rationale: "Tuya cloud hung on broken default v6 route; urllib3 pool exhaustion cancelled
      setup repeatedly. Applied via shell_command.ipv6_static_nogw ->
      /homeassistant/netfix_ipv6.sh (Supervisor network API). Verified after: Tuya loaded,
      light back, Matter Server started. If ever reverted: Settings > System > Network >
      enp1s0 > IPv6 = Auto."
    entities:
      - light.3d_printer_lights
    files:
      - configuration.yaml
      - netfix_ipv6.sh
    integrations:
      - tuya
      - matter
    status: superseded
  - id: 2026-08-23-enp1s0-ipv6-must-stay-auto-thread
    date: 2026-08-23
    title: enp1s0 IPv6 must stay Auto (Thread-Matter needs routed v6)
    decision: enp1s0 IPv6 stays Auto. Static-no-gateway breaks Thread-Matter (nodes
      fd25:f6c0:5149::/48 go ENETUNREACH); Auto breaks Tuya while Bell router v6 is
      broken. Real fix = reboot the router. netfix_ipv6.sh via
      shell_command.ipv6_static_nogw = quick toggle between modes if ever needed again.
    rationale: "2026-08-23: Bell GigaHub default v6 route black-holed apigw.tuyaus.com -> Tuya
      setup cancelled repeatedly. Static-no-gateway fixed Tuya but killed Thread-Matter
      within minutes (41/90 down). Auto restored all 90 Matter nodes; Tuya failed again ->
      router still broken. User will reboot it. After reboot verify BOTH tuya loaded AND 0
      matter unavailable; if still broken, fallback = SSH addon + manual route for
      fd25:f6c0:5149::/48 only."
    entities:
      - light.3d_printer_lights
    files:
      - configuration.yaml
      - netfix_ipv6.sh
    integrations:
      - tuya
      - matter
    status: superseded
    superseded_by: 2026-08-23-enp1s0-ipv6-must-stay-auto-thread-2
  - id: 2026-08-23-enp1s0-ipv6-must-stay-auto-thread-2
    date: 2026-08-23
    title: enp1s0 IPv6 must stay Auto (Thread-Matter needs routed v6)
    decision: enp1s0 IPv6 stays Auto. Static-no-gateway breaks Thread-Matter (nodes
      fd25:f6c0:5149::/48 go ENETUNREACH); Auto breaks Tuya while Bell router v6 is
      broken. Real fix = reboot the router. netfix_ipv6.sh via
      shell_command.ipv6_static_nogw = quick toggle between modes if ever needed again.
    rationale: "2026-08-23: Bell GigaHub default v6 route black-holed apigw.tuyaus.com -> Tuya
      setup cancelled repeatedly. Static-no-gateway fixed Tuya but killed Thread-Matter
      within minutes (41/90 down). Auto restored all 90 Matter nodes; Tuya failed again ->
      router still broken. User will reboot it. After reboot verify BOTH tuya loaded AND 0
      matter unavailable; if still broken, fallback = SSH addon + manual route for
      fd25:f6c0:5149::/48 only."
    entities:
      - light.3d_printer_lights
    files:
      - configuration.yaml
      - netfix_ipv6.sh
    integrations:
      - tuya
      - matter
    pin: true
    status: active
  - id: 2026-08-23-thread-outage-fix-cold-boot-google-tv
    date: 2026-08-23
    title: "Thread outage fix: cold-boot Google TV Streamer"
    decision: "If Matter/Thread nodes go unavailable after network disruption: unplug+replug
      the Google TV Streamer (Thread BR), wait ~10 min. Nodes rejoin only if cold boot
      restores its original Thread dataset; else re-pair needed. Restarting HA/Matter
      add-on does NOT help."
    rationale: "2026-08-23: Bell router reboot made TV Streamer re-form Thread mesh under new
      identity (XPAN BDE139547AD960A4 / fdbd:e139:547a:60a4); six Thread nodes stranded on
      dead fd25:f6c0:5149 formation — silent, invisible to mDNS. Add-on restart useless;
      cold boot restored dataset by 18:25. Google never exports credentials; permanent fix
      = HA-hosted OTBR on own radio."
    entities:
      - light.bedroom_lamp
      - light.office_lamp
      - sensor.bedroom_switch_battery
    integrations:
      - matter
      - thread
    status: superseded
    superseded_by: 2026-08-23-thread-outage-fix-cold-boot-google-tv-2
  - id: 2026-08-23-zbt-2-ordered-otbr-migration-plan
    date: 2026-08-23
    title: "ZBT-2 ordered: OTBR migration plan pending hardware"
    decision: "When Home Assistant Connect ZBT-2 arrives: install OpenThread Border Router
      add-on on it, form HA's own Thread network, then migrate the 6 Matter-over-Thread
      devices over-the-air per device (Add Device → scan label code → Move to HA's Thread
      Network). No factory resets expected; reset only as fallback."
    rationale: "2026-08-23: Recurring outages because Google TV Streamer owns the Thread mesh
      and re-forms it with fresh credentials after disruptions, stranding nodes. It never
      exports its dataset, so no seamless import — but devices already sit in HA's Matter
      fabric, so per-device OTA migration works without reset. Keep TV Streamer online
      until all 6 moved, then disable its hub radio in Google Home app. End state: border
      routers visible in HA Thread integration, router reboots harmless."
    entities:
      - light.bedroom_lamp
      - light.office_lamp
      - sensor.bedroom_switch_battery
    integrations:
      - matter
      - thread
    status: superseded
    superseded_by: 2026-08-23-zbt-2-ordered-otbr-migration-plan-2
  - id: 2026-08-23-thread-outage-fix-cold-boot-google-tv-2
    date: 2026-08-23
    title: "Thread outage fix: cold-boot Google TV Streamer"
    decision: "If Matter/Thread nodes go unavailable after network disruption: unplug+replug
      the Google TV Streamer (Thread BR), wait ~10 min. Nodes rejoin only if cold boot
      restores its original Thread dataset; else re-pair needed. Restarting HA/Matter
      add-on does NOT help."
    rationale: "2026-08-23: Bell router reboot made TV Streamer re-form Thread mesh under new
      identity (XPAN BDE139547AD960A4 / fdbd:e139:547a:60a4); six Thread nodes stranded on
      dead fd25:f6c0:5149 formation — silent, invisible to mDNS. Add-on restart useless;
      cold boot restored dataset by 18:25. Google never exports credentials; permanent fix
      = HA-hosted OTBR on own radio."
    entities:
      - light.bedroom_lamp
      - light.office_lamp
      - sensor.bedroom_switch_battery
    integrations:
      - matter
      - thread
    pin: true
    status: active
  - id: 2026-08-23-zbt-2-ordered-otbr-migration-plan-2
    date: 2026-08-23
    title: "ZBT-2 ordered: OTBR migration plan pending hardware"
    decision: "When Home Assistant Connect ZBT-2 arrives: install OpenThread Border Router
      add-on on it, form HA's own Thread network, then migrate the 6 Matter-over-Thread
      devices over-the-air per device (Add Device → scan label code → Move to HA's Thread
      Network). No factory resets expected; reset only as fallback."
    rationale: "2026-08-23: Recurring outages because Google TV Streamer owns the Thread mesh
      and re-forms it with fresh credentials after disruptions, stranding nodes. It never
      exports its dataset, so no seamless import — but devices already sit in HA's Matter
      fabric, so per-device OTA migration works without reset. Keep TV Streamer online
      until all 6 moved, then disable its hub radio in Google Home app. End state: border
      routers visible in HA Thread integration, router reboots harmless."
    entities:
      - light.bedroom_lamp
      - light.office_lamp
      - sensor.bedroom_switch_battery
    integrations:
      - matter
      - thread
    pin: true
    status: superseded
  - id: 2026-08-24-octoprint-rest-sensors-stay-on-duckdns
    date: 2026-08-24
    title: OctoPrint REST sensors stay on DuckDNS URL — local-address fix deferred
    decision: "Keep all OctoPrint rest: sensors polling via https://ender5pro.duckdns.org. Do
      not switch them to OctoPrint's LAN address unless the user asks."
    rationale: "2026-08-24 outage: the public path failed intermittently 11:39-16:45 EDT
      (empty replies, openresty 502, conn refused, timeouts) and the
      filament/recent-prints sensors went unavailable ~16:40 before self-recovering at the
      next poll. Pointing the rest: block at OctoPrint's local address was proposed as
      hardening; user chose to leave it as-is. Revisit only if these outages recur."
    entities:
      - sensor.octoprint_filament_used_total
      - sensor.octoprint_filament_used_weight_total
      - sensor.octoprint_recent_prints
    files:
      - configuration.yaml
    status: active
  - id: 2026-08-27-ender-printer-cams-use-main-profile
    date: 2026-08-27
    title: Ender printer cams use Main-profile go2rtc transcode
    decision: "The octoprint/octoprint2 H264 camera streams in go2rtc.yaml are transcoded with
      a custom 'h264_octo' template (Main profile, level 4.0, capped 4-6Mbps bitrate)
      instead of go2rtc's default High profile. This fixed choppy/slow video in the
      Android HA app. Do not revert to the plain #video=h264 for these streams."
    rationale: go2rtc's default High-profile H264 was incompatible with the Android WebView
      MSE decoder, causing falls back to WebRTC and choppy playback. Main profile + capped
      bitrate keeps 1080p and plays smoothly. Intentionally only affects the Ender
      cameras; nest/blink streams left on default.
    entities:
      - camera.ender_camera
      - camera.ender_camera_2
    files:
      - go2rtc.yaml
    integrations:
      - webrtc
    pin: true
    status: active
  - id: 2026-08-28-filter-plug-is-hardware-faulty-replace
    date: 2026-08-28
    title: Filter plug is hardware-faulty; replace as "Air Purifier"
    decision: 'The Filter plug (0xffffb40e060893d8, switch.filter) is hardware-faulty:
      downlink fails with MAC_CHANNEL_ACCESS_FAILURE (0xe1) despite clean re-pair and
      relocation; uplink/button/other devices work. Do not re-diagnose. Scheduled for
      replacement, to be named "Air Purifier".'
    rationale: Clean re-pair and relocation next to the coordinator both failed to resolve
      identical 0xe1 errors on downlink-only commands; physical button and uplink
      telemetry work, and no other device shares the fault. Diagnosis of a defective
      receive/ack path is final. Replacement gets a new IEEE, so
      zigbee2mqtt/configuration.yaml must be re-pointed to it and the name set to "Air
      Purifier".
    entities:
      - switch.filter
      - sensor.0xffffb40e060893d8_linkquality
    files:
      - zigbee2mqtt/configuration.yaml
    integrations:
      - zigbee2mqtt
    pin: true
    status: superseded
  - id: 2026-08-28-filter-plug-hardware-faulty-replacing
    date: 2026-08-28
    title: Filter plug hardware-faulty; replacing with Matter plugs
    decision: "Filter plug (0xffffb40e060893d8) is hardware-faulty: downlink fails with 0xe1
      despite clean re-pair and relocation; uplink/button/other devices work. Do not
      re-diagnose. Being replaced by Kasa KP125M Matter (Wi-Fi) plugs; no Z2M re-pair.
      Entity IDs change — re-point references."
    rationale: Supersedes earlier note assuming a Zigbee replacement. Clean re-pair plus
      relocation next to the coordinator both failed to resolve identical 0xe1 errors on
      downlink-only commands; button and uplink work, no other device shares the fault.
      Replacement is 4x Kasa KP125M Matter (Wi-Fi, energy monitoring). Commission via
      Matter add-on; entity IDs change, so printer/health automations and dashboard tile
      need re-pointing.
    entities:
      - switch.filter
      - sensor.0xffffb40e060893d8_linkquality
    integrations:
      - matter
      - 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: superseded
    superseded_by: 2026-08-29-filter-plug-kasa-kp125m-on-native
  - id: 2026-08-29-filter-plug-kasa-kp125m-on-native
    date: 2026-08-29
    title: Filter plug = Kasa KP125M on native tplink; Matter path dropped
    decision: "Filter plug replaced: old Zigbee 0xffffb40e060893d8 was hardware-faulty (0xe1;
      do not re-diagnose). Replacement is a Kasa KP125M on the native tplink integration,
      NOT Matter. Entities renamed to filter_ prefix (switch.filter,
      sensor.filter_current_consumption, etc.); dashboard tile and health-alert refs
      cleaned."
    rationale: Outcome supersedes the earlier "KP125M Matter plugs" plan. Matter was verified
      to expose no power/energy entities, so tplink config-flow auto-discovery was used
      instead. Entity-IDs were client-renamed, so the dashboard tile had to be manually
      repointed to sensor.filter_current_consumption.
    entities:
      - switch.filter
      - sensor.filter_current_consumption
    integrations:
      - tplink
    pin: true
    status: superseded
    superseded_by: 2026-08-29-filter-plug-kasa-kp125m-on-matter
  - id: 2026-08-29-new-kasa-devices-native-tplink-legacy
    date: 2026-08-29
    title: New Kasa devices → native tplink; legacy Homebridge-bridged Kasa untouched
    decision: "Kasa has two paths: legacy devices bridged into HA via a Homebridge plugin
      (leave untouched); new devices go on the native tplink integration going forward.
      Homebridge add-on may be removed at some point, only after verifying nothing still
      depends on it."
    rationale: No working Kasa HACS integration existed when the legacy devices were set up,
      so they were bridged via Homebridge. Both coexist now; do not migrate or disturb the
      existing bridged entities, and if the Homebridge add-on is ever removed, first
      confirm nothing (dashboards/automations) references the bridged entities.
    integrations:
      - tplink
      - homekit_controller
    pin: true
    status: superseded
    superseded_by: 2026-08-29-new-kasa-devices-native-tplink-except
  - id: 2026-08-29-tplink-kasa-entries-are-discovery-based
    date: 2026-08-29
    title: tplink/Kasa entries are discovery-based; IP changes handled automatically
    decision: "tplink/Kasa entries are discovery-based (not IP-bound): if a plug's IP changes,
      HA re-discovers it automatically; no re-pairing needed and fixed IPs are not
      required. Do not re-pair or pin IPs in response to an IP change."
    rationale: User asked whether IP changes would break the tplink integration. The config
      entry (01M182SQ9M0SJDN9DTXTCG2QZA) is source 'user' with no IP pinned; HA 2024.1+
      python-kasa discovery rebroadcasts handle IP changes. Brief 'unavailable' window is
      normal and self-healing; a DHCP reservation is optional.
    entities:
      - switch.filter
    integrations:
      - tplink
    status: active
  - id: 2026-08-29-filter-plug-kasa-kp125m-on-matter
    date: 2026-08-29
    title: Filter plug = Kasa KP125M on Matter; tplink path removed
    decision: "Filter plug is a Kasa KP125M on Matter only: HA Matter (sw 1.3) exposes
      power/voltage/current/energy/energy-exported, so the native tplink entry was
      removed. Entities renamed to filter_* (switch.filter,
      sensor.filter_current_consumption, sensor.filter_energy). Do not re-add the tplink
      path."
    rationale: 'Initial verification showed Matter exposing no power/energy entities, so
      native tplink auto-discovery was used. However, when Matter firmware 1.3 confirmed
      it reports power/voltage/current/energy/energy-exported, the plug was migrated to
      Matter-only: tplink config entry (01M182SQ9M0SJDN9DTXTCG2QZA) removed, Matter
      entities renamed to keep the filter_* IDs so existing automations and dashboards
      resolved unchanged. Replacing the previous note that said "tplink, NOT Matter".'
    entities:
      - switch.filter
      - sensor.filter_current_consumption
      - sensor.filter_energy
    integrations:
      - matter
      - tplink
    pin: true
    status: active
  - id: 2026-08-29-new-kasa-devices-native-tplink-except
    date: 2026-08-29
    title: New Kasa devices → native tplink, except filter plug on Matter; Homebridge legacy
      untouched
    decision: "Kasa has two paths: legacy devices bridged via a Homebridge plugin (leave
      untouched); new devices go on native tplink — except the filter plug (KP125M), which
      is on native Matter. Remove Homebridge only after verifying nothing depends on its
      devices."
    rationale: "Original note recorded the two-path Kasa setup. Amended 2026-08-29 to record
      the new exception: the filter plug uses the native Matter integration rather than
      tplink (Matter 1.3 firmware exposes power/voltage/current/energy). Both the
      Homebridge-bridged devices and native-tplink guidance stay in force."
    entities:
      - switch.filter
    integrations:
      - tplink
      - homekit_controller
      - matter
    pin: true
    status: active
  - id: 2026-08-29-office-plug-removed-from-z2m-as-faulty
    date: 2026-08-29
    title: Office Plug removed from Z2M as faulty, replaced
    decision: The Z2M 'Office Plug' (Third Reality 3RSP02028BZ, IEEE 0xffffb40e060893d8) was
      removed from the mesh on 2026-08-29 as faulty and is being replaced. Its entities
      (switch.office_plug, sensor.office_plug_*) are gone and nothing references them. Do
      not re-add the old device IEEE.
    rationale: User decided to replace the plug despite diagnostics showing healthy radio
      publishing; records the deliberate removal so a future session does not try to
      restore the old device IEEE or the removed entities.
    entities:
      - switch.office_plug
    integrations:
      - zigbee2mqtt
    status: superseded
    superseded_by: 2026-08-29-office-plug-removed-from-z2m-as-faulty-2
  - id: 2026-08-29-office-plug-removed-from-z2m-as-faulty-2
    date: 2026-08-29
    title: Office Plug removed from Z2M as faulty, replaced by Kasa Matter plug
    decision: The Z2M 'Office Plug' (Third Reality 3RSP02028BZ, IEEE 0xffffb40e060893d8) was
      removed from the mesh on 2026-08-29 as faulty and replaced by the Kasa KP125M plug
      on Matter (switch.filter). Its entities are gone, nothing references them, and the
      old IEEE must not be re-added.
    rationale: Amended to record that the replacement plug is the Kasa KP125M on Matter
      (switch.filter), matching the pinned filter-plug notes, so a future session sees the
      full remove-and-replace link instead of a vague 'is being replaced'. Original note
      said the plug was faulty and 'is being replaced' without naming the Kasa Matter
      plug.
    entities:
      - switch.office_plug
      - switch.filter
    integrations:
      - zigbee2mqtt
      - matter
    status: active
  - id: 2026-09-06-octoprint-height-widget-uses-clean
    date: 2026-09-06
    title: OctoPrint height widget uses clean template sensor, not raw REST sensor
    decision: OctoPrint height widget must point at sensor.octoprint_height_progress_clean. Do
      not delete this template sensor or repoint the widget to the raw REST sensor — its
      float32 total attribute and display_precision 0 default round the widget display.
    rationale: Widget shows state + total attribute in one tile. The REST sensor's total
      attribute is a float32 artifact (75.5999984741211) from the DisplayLayerProgress
      plugin JSON and cannot be transformed at source; its display_precision 0 default
      rounds the widget current value up (85.6 -> 86). The YAML template sensor
      (configuration.yaml template block) re-exposes state and total rounded to 1 decimal,
      with its own display_precision set to 1.
    entities:
      - sensor.octoprint_height_progress_clean
      - sensor.octoprint_height_progress
    files:
      - configuration.yaml
    integrations:
      - rest
      - template
    status: superseded
    superseded_by: 2026-09-06-octoprint-height-widget-uses-clean-2
  - id: 2026-09-06-nest-snapshot-custom-integration
    date: 2026-09-06
    title: nest_snapshot custom integration abandoned
    decision: nest_snapshot integration is abandoned. WebRTC SDP parsing was fixed but ICE
      connection to Google Nest's ice-lite candidates never establishes (30s timeout). Do
      not revisit.
    rationale: After resolving SDP candidate format issues (missing component-id), aiortc
      could parse Google's answer but ICE connectivity checks timed out every time across
      multiple restarts. Track handler fires but recv() never gets a frame. Root cause
      undetermined — likely aiortc STUN connectivity or ice-lite compatibility issue. Not
      worth further effort.
    files:
      - custom_components/nest_snapshot/__init__.py
      - custom_components/nest_snapshot/manifest.json
      - custom_components/nest_snapshot/services.yaml
    integrations:
      - nest_snapshot
    status: active
  - id: 2026-09-06-octoprint-height-widget-uses-clean-2
    date: 2026-09-06
    title: OctoPrint height widget uses clean template sensor, not raw REST sensor
    decision: OctoPrint height widget must point at sensor.octoprint_height_progress_clean. Do
      not delete this template sensor or repoint the widget to the raw REST sensor — its
      float32 total attribute and display_precision 0 default round the widget display.
    rationale: Widget shows state + total attribute in one tile. The REST sensor's total
      attribute is a float32 artifact (75.5999984741211) from the DisplayLayerProgress
      plugin JSON and cannot be transformed at source; its display_precision 0 default
      rounds the widget current value up (85.6 -> 86). The YAML template sensor
      (configuration.yaml template block) re-exposes state and total rounded to 1 decimal,
      with its own display_precision set to 1.
    entities:
      - sensor.octoprint_height_progress_clean
      - sensor.octoprint_height_progress
    files:
      - configuration.yaml
    integrations:
      - rest
      - template
    pin: true
    status: active
  - id: 2026-09-17-printer-stale-boolean-gets-a-reset
    date: 2026-09-17
    title: Printer stale boolean gets a reset bounce
    decision: Do not delete automation.3d_printer_running_reset_stale_boolean — it bounces
      input_boolean.3d_printer_running off->on when commanded on while already stale
      (>5s), ensuring the main print automation fires.
    rationale: "A printer crash left input_boolean.3d_printer_running ON, so the plugin's
      turn_on was a no-op and the main automation missed the print start. The reset
      automation bounces the boolean off->2s->on when turn_on fires while already stale
      (>5s), synthesising the off->on transition the main automation needs. Verified live:
      the bounce works and the >5s check prevents re-triggering from its own turn_on. Do
      not delete."
    entities:
      - input_boolean.3d_printer_running
      - automation.3d_printer_running_reset_stale_boolean
      - automation.3d_printer_running_playroom_light_basement_heat
    status: active
  - id: 2026-09-28-sparkx-camera-picture-entity-live-card
    date: 2026-09-28
    title: "SparkX camera: picture-entity live card, reload integration to fix hung feed"
    decision: "SparkX camera: use picture-entity with camera_view: live, never
      custom:webrtc-camera. Hung feed = stale printer WebRTC session; reload the
      ha_creality_ws entry to fix (no restart). Snapshots need light.sparkx_i7_light on."
    rationale: "No MJPEG (8080 refused) or RTSP on the printer, so its native WebRTC endpoint
      is the only source and go2rtc (via ha_creality_ws) the only relay. webrtc-camera was
      tried with url: and entity: modes and stayed black. A stale upstream session leaves
      the stream registered but carrying no media, so the frontend shows a permanent
      Loading spinner - the card was never at fault. Keep the #format=creality fragment in
      the go2rtc source or the printer returns an empty SDP."
    entities:
      - camera.sparkx_i7_printer_camera
      - light.sparkx_i7_light
    files:
      - go2rtc.yaml
    integrations:
      - ha_creality_ws
      - webrtc
    status: active