# 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: active
  - 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