zorruno-homeassistant/PROJECTS.md

Project Tracker

Use this file as the source of truth for projects being worked on with OpenCode.

• Associate each user request with a project ID before beginning work.
• Ask the user which project applies when the request is ambiguous.
• Keep project IDs stable and use the relevant section to store durable context.
• Update context as work progresses, subject to the approval rules in AGENTS.md.
• Never mark a project complete unless the user explicitly confirms it is complete.
• Ask the user before closing a project that appears complete.
• Use these statuses: Active, Paused, and Complete.

Active Projects

ID	Project	Status	Next Step	Last Updated
P001	Bedside panel alarm audio	Active	Deploy and verify alarm audio and volume behavior.	2026-07-20
P002	reTerminal E1001 dashboard	Active	Test display refresh, wake buttons, MQTT control, and deep sleep.	2026-07-20
P003	ESPHome MQTT topic normalization	Active	Compile and deploy both stair devices, then verify HA-down MQTT synchronization.	2026-07-21
P004	Appliance completion announcements	Active	Test an appliance cycle and resolve feed/timestamp inconsistencies.	2026-07-20
P006	Bedside rain forecast	Active	Verify forecast boundaries and API-failure handling.	2026-07-20
P013	Full Home Assistant system audit	Active	Complete a comprehensive read-only audit and present prioritized recommendations.	2026-07-21

Completed Projects

ID	Project	Status	Next Step	Last Updated
P005	Jobs and Chore Tracker V2.3	Complete	None.	2026-07-21
P007	Bedtime stair shutdown	Complete	None.	2026-07-21
P008	Spook unused entity cleanup	Complete	None.	2026-07-21
P009	Lounge front-door camera layout	Complete	None.	2026-07-21
P010	Main-page Jobs timing gauges	Complete	None.	2026-07-21
P011	Downstairs occupancy helper cleanup	Complete	None.	2026-07-21
P012	EdgeRouter X SNMP monitoring	Complete	None.	2026-07-21

Project Details

P001: Bedside Panel Alarm Audio

• Objective: Provide reliable local alarm audio and user-adjustable volume on the bedside panel.
• Current context: ES8311 and I2S output, amplifier control, persistent volume, and Beep/Alarm/Stop controls were added and repeatedly tuned. Compilation, deployment, and hardware behavior have not been confirmed.
• Key files: esphome/esp-bedside-panel.yaml.
• Known issue: The file changelog records V1.47 while project_version still reports v1.46.
• Next step: Compile and deploy, then test startup noise, Beep/Alarm/Stop, volume endpoints, persistence, and amplifier shutdown.
• Activity: 2026-07-20 - Implemented and tuned the alarm-audio feature through V1.47.

P002: reTerminal E1001 Dashboard

• Objective: Build a low-power e-paper dashboard for job and appliance status.
• Current context: Added ESP32-S3 hardware support, Jobs and Appliances pages, Home Assistant entity imports, icons, buttons, MQTT controls, change-only refresh, retained page hashes, wake-source handling, and deep sleep. Runtime behavior has not been confirmed.
• Key files: esphome/esp-reterminal-e1001.yaml.
• Next step: Compile and deploy, then test entity data, rendering, page buttons, timer and button wake, MQTT keep-awake control, fallback sleep, and battery usage.
• Activity: 2026-07-20 - Created the device configuration and developed it through v0.6.1.

P003: ESPHome MQTT Topic Normalization

• Objective: Simplify MQTT command and status topics across related ESPHome devices while preserving synchronization.
• Current context: Flattened component-specific MQTT topics to logical device roots across eleven devices. Updated paired lounge and master-bedroom consumers and restored direct pantry-light control. The central-stair top and bottom source configurations are now v3.9: physical states publish retained QoS 1 status, remote mirrors consume those status topics, commands remain non-retained, and the superseded lounge-middle member was removed from the HA sync group.
• Key files: Related device configurations under esphome/, including esphome/esp-centralstairs-top.yaml, esphome/esp-centralstairs-bottom.yaml, and packages/Lighting_2Way_Sync/central_stairway_2way_sync.yaml.
• Verification: Both stair ESPHome files parse, Home Assistant configuration validation passed, and both two-member relay pairs synchronized on and off in both directions through Home Assistant. ESPHome compile/upload and HA-down MQTT behavior remain unverified because OpenCode does not have the required Long-Lived Access Token.
• Next step: Configure the OpenCode ESPHome token, compile and deploy both stair devices together, test direct MQTT commands and retained status with HA Core unavailable, then continue the broader paired-device and external-client audit.
• Activity: 2026-07-20 - Applied the MQTT topic normalization across the related devices.
• Activity: 2026-07-21 - Added retained MQTT status mirroring to both central-stair v3.9 source files, removed the superseded lounge-middle HA member, validated the source, and live-tested both HA relay pairs.

P004: Appliance Completion Announcements

• Objective: Route appliance completion events to configured announcement channels and MQTT activity feeds.
• Current context: Added per-appliance announcement settings, payloads, channels, LED-matrix indicators, MQTT feed suffixes, suppression logging, retained attributes, and expanded washer, dryer, dishwasher, and EV-charger handling.
• Key files: packages/Appliance_Monitoring/appliance_monitor_processor.yaml, packages/Appliance_Monitoring/appliances_status_monitoring.yaml, packages/view_road_announcement_router.yaml, and packages/appliance_status_mqttfeed.yaml.
• Known issues: MQTT feed channels may not yet be enabled for each appliance, and timestamp sensors may receive time-only payloads.
• Next step: Resolve the feed and timestamp inconsistencies, then test a complete appliance cycle end to end.
• Activity: 2026-07-20 - Expanded appliance monitoring and completion-feed routing.

P005: Jobs and Chore Tracker V2.3

• Objective: Maintain household jobs through a registry-driven tracker with discovery entities and completion windows.
• Current context: Centralized five jobs, added generic completion routing, morning and evening dog-feeding windows, MQTT Discovery entities, summary and count entities, manual buttons, missed-job handling, and completion-window expiry.
• Key files: packages/Job_Chore_Tracking/jobs_tracker_jobs.yaml and packages/Job_Chore_Tracking/jobs_tracker_processor.yaml.
• Known issue: Some count entities may be stale or have duplicated jobs_tracker naming.
• Next step: None.
• Activity: 2026-07-20 - Implemented the V2.3 registry and processor changes.
• Activity: 2026-07-21 - User confirmed completion.

P006: Bedside Rain Forecast

• Objective: Supply the bedside panel with useful rain-chance forecasts for today and tomorrow.
• Current context: Added Open-Meteo REST sensors for today's remaining forecast period and tomorrow's daylight period using the Home zone coordinates.
• Key files: packages/open_meteo_rain_chance.yaml and esphome/esp-bedside-panel.yaml.
• Next step: Verify sunrise and sunset boundary behavior, stale-data handling, and API-failure recovery.
• Activity: 2026-07-20 - Added the Open-Meteo rain forecast package and bedside-panel inputs.

P007: Bedtime Stair Shutdown

• Objective: Ensure the central stair lighting turns off as part of bedtime mode.
• Current context: The lower main stair lights and stair footer lights are included in the bedtime shutdown sequence with no delay. Their HA two-way groups now contain only the active top and bottom relays; the superseded lounge-middle member was removed.
• Key files: packages/bedtime_mode_actions.yaml and packages/Lighting_2Way_Sync/central_stairway_2way_sync.yaml.
• Verification: Both bottom relays were turned on and the exact zero-delay bedtime shutdown script turned both off. The corresponding top relays followed to off. After the obsolete third member was removed, each two-member pair also synchronized on and off successfully in both HA directions.
• Next step: None.
• Activity: 2026-07-20 - Added both central stair relays to bedtime shutdown.
• Activity: 2026-07-21 - Live-tested both bedtime shutdown targets and both HA two-way relay pairs; all tests passed and the user confirmed completion.

P008: Spook Unused Entity Cleanup

• Objective: Resolve Spook warnings caused by stale entity references.
• Current context: The Master Bedroom Echo Show Environment view now uses the live Bedroom 1 Environment (Z19TH) temperature and humidity entities, and the related Spook repair has cleared.
• Replacement entities: sensor.bedroom_1_environment_z19th_temperature and sensor.bedroom_1_environment_z19th_humidity.
• Verification: The stored card definitions reference the replacement entities, and Spook no longer reports the Master Bedroom Echo Show issue. Automated visual verification was unavailable because the screenshot tool is disabled.
• Next step: None.
• Activity: 2026-07-21 - Created the project and selected the live Bedroom 1 Environment (Z19TH) sensor pair.
• Activity: 2026-07-21 - Replaced both stale dashboard references and confirmed that the Spook repair cleared.
• Activity: 2026-07-21 - User confirmed completion.

P009: Lounge Front-Door Camera Layout

• Objective: Display the Front Door Camera in landscape orientation on the Lounge dashboard.
• Current context: The Lounge Home view now displays the live camera.camera2 card at a 4:3 landscape aspect ratio.
• Verification: The saved view retains all seven cards and the Front Door Camera live-view settings, and camera.camera2 is streaming. Automated visual verification was unavailable because the screenshot tool is disabled.
• Next step: None.
• Activity: 2026-07-21 - Created the project and identified the Front Door Camera card on the Lounge Home view.
• Activity: 2026-07-21 - Changed the Front Door Camera card from 3:4 to 4:3 and verified the saved dashboard configuration.
• Activity: 2026-07-21 - User confirmed completion.

P010: Main-Page Jobs Timing Gauges

• Objective: Make the Lounge Home dog-feeding and depooping gauges use timing from the Jobs routine.
• Current context: The gauges use numeric-safe Jobs-derived template sensors. Dog feeding uses the latest valid morning/evening completion, and depooping uses the weekly job completion. Jobs startup waits for retained timestamps before refreshing, and stale restored event timestamps cannot mark jobs complete.
• Selected design: Keep two gauges. Dog feeding uses the latest morning/evening completion; depooping uses the weekly job completion.
• Key files: packages/pet_feeding_and_jobs.yaml and packages/Job_Chore_Tracking/jobs_tracker_jobs.yaml.
• Verification: Home Assistant accepted the v1.1.0 gauge templates and V2.4 Jobs configuration. Invalid feeding attributes produced unavailable instead of 999999, the retained-state readiness guard passed, the stale restored depooping event failed the freshness guard, a subsequent minute refresh preserved the recovered timestamps, and the gauges reported 23 hours fed and 162 hours depooped. Automated visual verification was unavailable because the screenshot tool is disabled.
• Next step: None.
• Activity: 2026-07-21 - Created the project and selected the two-gauge Jobs-derived design.
• Activity: 2026-07-21 - Added the Jobs-derived sensors, reloaded templates, and updated both Lounge Home gauges.
• Activity: 2026-07-21 - User confirmed completion.
• Activity: 2026-07-21 - Fixed a restart race that erased retained feeding timestamps, blocked stale restored event states from creating false completions, removed the 999999 fallback, restored the last valid Jobs timestamps from recorder history, and verified 23-hour/162-hour gauge values.

P011: Downstairs Occupancy Helper Cleanup

• Objective: Eliminate the duplicate downstairs guest occupancy helper.
• Canonical helper: input_boolean.downstairs_flat_occupied, which is YAML-managed and used by the downstairs lockout behavior.
• Removed duplicate: input_boolean.guest_area_occupied, which was UI-managed and referenced only by the Test dashboard.
• Current context: All nine stored Test dashboard references now use the canonical helper, the duplicate helper has been deleted, and the Lounge row of eight downstairs-flat light icons now greys out and blocks taps while occupied.
• Verification: The duplicate returns entity not found, the canonical helper remains available with its automation and script relationships, no Test dashboard broken-reference repair was created, and the saved Lounge templates render both the enabled and occupied branches correctly. Automated visual verification was unavailable because the screenshot tool is disabled.
• Next step: None.
• Activity: 2026-07-21 - Created the project and completed the dependency audit.
• Activity: 2026-07-21 - Migrated the Test dashboard references and deleted the duplicate helper.
• Activity: 2026-07-21 - Added occupancy-driven greying and tap blocking to the Lounge downstairs-flat light row.
• Activity: 2026-07-21 - User verified the Lounge lockout and confirmed completion.

P012: EdgeRouter X SNMP Monitoring

• Objective: Restore EdgeRouter X monitoring on firmware v3.0.x using a compatible SNMP-based approach.
• Current context: EdgeOS v2.1.9 is incompatible with EdgeOS v3.0.1. SNMP monitoring now provides major-interface traffic rates and router health data, and the three existing Internet traffic entities use the WAN SNMP derivatives. The old EdgeOS config entry is disabled and reversible; its config entry, entities, devices, and HACS files have not been deleted.
• Verification: Backup 1b6dd6d8 contains Home Assistant, the database, folders, and all apps on both backup agents with no failed components. Home Assistant configuration validation and restart succeeded. After disabling EdgeOS, all 31 SNMP entities and the three preserved Internet traffic entities remained available; all 210 old entities remained registered, with 208 unavailable and two having no current state.
• Next step: None.
• Activity: 2026-07-21 - Created the project and began the compatibility investigation.
• Activity: 2026-07-21 - Confirmed the EdgeOS v3.0.1 API incompatibility and validated read-only SNMPv2c access, interface indices, traffic counters, and health OIDs.
• Activity: 2026-07-21 - Added packages/edgerouter_snmp.yaml, migrated the existing Internet traffic templates to WAN SNMP derivatives, restarted Home Assistant, and verified live values.
• Activity: 2026-07-21 - Audited old EdgeOS dependencies, found no remaining YAML or dashboard references, disabled the config entry, and verified SNMP monitoring remained operational.
• Activity: 2026-07-21 - Documented packages/edgerouter_snmp.yaml as v1.0.0 using zorruno package and section headers; Home Assistant configuration validation passed.
• Activity: 2026-07-21 - Updated the SNMP package to v1.0.1, moved all router host values to !secret edgerouter_host, passed configuration validation, restarted Home Assistant, and verified all 31 SNMP entities plus the three Internet traffic entities remained available while EdgeOS stayed disabled.
• Activity: 2026-07-21 - User confirmed completion.

P013: Full Home Assistant System Audit

• Objective: Perform a comprehensive read-only audit of the Home Assistant installation and present prioritized fixes, changes, and improvements.
• Audit report: P013_AUDIT_RESULTS.md
• Scope: Configuration validity and deprecations; runtime and integration health; entities and devices; automations, scripts, scenes, and helpers; dashboards; MQTT, Zigbee, and ESPHome; backups and updates; recorder and performance; and security posture without exposing secrets.
• Current context: Audit created at the user's request. No Home Assistant state, registry, integration, dashboard, firmware, or configuration changes are authorized as part of the audit.
• Next step: Gather evidence through supported configuration files, MCP tools, hab, and zigporter, then present findings ordered by severity and impact.
• Activity: 2026-07-21 - Created the project and began the comprehensive read-only audit.
• Activity: 2026-07-22 - Resolved P013-F002 by sanitizing and archiving three retired ESPHome configurations; the user accepted the residual historical Git copies because the keys do not match current secrets or active devices.