site structure

Author: webosa

docs/smart-home/automations.md

@@ -1,22 +1,19 @@
-# Automations & Packages
+---
+tags:
+  - automations
+  - ui
+  - automated
+---
 
-This page documents the automation packages found in the `packages/` directory.
+# UI Automations
 
-| File | Purpose | Triggers | Key Entities |
+This page documents automations that are managed directly via the Home Assistant UI (`automations.yaml`). 
+
+!!! info "Package Automations"
+    Automations that are part of a specific feature bundle (e.g., Car, Heating) are documented in the **[Package Catalog](packages/index.md)**.
+
+## Active UI Automations
+
+| Alias | Description | Trigger Types | Mode |
 | :--- | :--- | :--- | :--- |
-| `airthings.yaml` | Air quality sensors template | *(Template)* | `sensor.airthings_wave_*` |
-| `aqara_w500.yaml` | HVAC/Temp sensors & filters | *(Template)* | `sensor.aqara_w500_*` |
-| `car_glc.yaml` | Car status normalization | *(Template)* | `binary_sensor.car_glc_*` |
-| `dishwasher.yaml` | Dishwasher status & timer logic | *(Template)* | `binary_sensor.dishwasher_*`, `input_boolean.dishwasher_*` |
-| `dna_tv_hub.yaml` | TV Hub remote switch | *(Template)* | `switch.dna_tv_hub` |
-| `fingerprint_management.yaml` | Dynamic Fingerprint MQTT Management | MQTT (`.../user/set`) | `script.add_fingerprint_entity`, `automation.system_fingerprint_mqtt_persistence` |
-| `garmin.yaml` | *(Empty)* | - | - |
-| `home_time_modes.yaml` | Time-of-Day Logic (Day/Night/Evening) | Time, Sun, Time Pattern | `input_select.house_mode`, `automation.system_manager_home_time_modes` |
-| `mercedes_glc.yaml` | Car control & sensors | *(Template)* | `switch.car_*`, `binary_sensor.car_*` |
-| `nordpool_prices.yaml` | Electricity prices & 15min cost calculation | Time Pattern, HA Start, State | `sensor.electricity_prices`, `nordpool.get_prices_for_date` |
-| `office._pc.yaml` | Office PC Control (WOL, Audio, Display) | *(Template/WOL)* | `switch.office_pc_*` |
-| `philips_air_purifier.yaml` | Air Purifier sensors | *(Template)* | `sensor.purifier_*` |
-| `room_automation.yaml` | Dynamic Room Settings via MQTT | MQTT (`room/#`), HA Start, Time Pattern | `script.create_room_settings`, `automation.system_populate_room_list` |
-| `scenes.yaml` | Lighting Scene Definitions | - | `scene.daylight_scene`, `scene.bedroom_mood`, etc. |
-| `shelly_3em.yaml` | Total Power Aggregation | *(Template)* | `sensor.home_total_power`, `sensor.home_energy_15min` |
-| `smart_notifications.yaml` | Dynamic Notification Router & User Mgmt | HA Start, Time Pattern, MQTT (`notify/#`) | `script.notify_smart_master`, `automation.system_populate_notify_services` |
+| Turn off Coffee Machine Outlet, when schedule is turned on | No description. | state | `single` |\n| Fetch Tomorrow Prices | No description. | time | `single` |\n| Fetch Today Prices | No description. | time | `single` |\n| Notify: Energy Price (Today & Tomorrow) | Sends 'Today's Prices' at 07:00 and 'Tomorrow's Prices' when available. | state, time | `single` |\n| G4 Doorbell - Event Stream to Nest Hub | Streams G4 Doorbell video to Bedroom Display only on doorbell press (24/7) or person on porch (daytime). | numeric_state, state | `single` |\n| Notify: Coffee Ready | Send notification when coffee machine finishes running | state | `single` |\n| Notify: Doorbell Actions | Notify phones with snapshot when doorbell rings, allowing unlock or DND message. | state | `restart` |

docs/smart-home/index.md

@@ -1,3 +1,9 @@
+---
+tags:
+  - index
+  - automated
+---
+
 # Smart Home Overview
 
 This section contains all architectural documentation for the Home Assistant setup, including automations, dashboards, and integrations.
@@ -7,29 +13,15 @@ This section contains all architectural documentation for the Home Assistant set
 - **[Configuration & Structure](structure.md)**:
   Detailed explanation of the **highly commented configuration.yaml** and the full **directory structure** (file tree). This is the best place to start understanding how the system is organized.
 
-- **[Dashboards](dashboards.md)**:
-  Overview of the Lovelace dashboards, view strategies, and custom cards used in the frontend.
-
-## Packages
-The system uses the `packages/` folder to bundle related automations, scripts, and configurations. Below is an index of the available packages:
-
-- **[Airthings](packages/airthings.md)**
-- **[Aqara W500](packages/aqara_w500.md)**
-- **[Car GLC](packages/car_glc.md)**
-- **[Dishwasher](packages/dishwasher.md)**
-- **[DNA TV Hub](packages/dna_tv_hub.md)**
-- **[Fingerprint Mgmt](packages/fingerprint_management.md)**
-- **[Garmin](packages/garmin.md)**
-- **[Home Time Modes](packages/home_time_modes.md)**
-- **[Mercedes GLC](packages/mercedes_glc.md)**
-- **[Nordpool Prices](packages/nordpool_prices.md)**
-- **[Office PC](packages/office_pc.md)**
-- **[Philips Air Purifier](packages/philips_air_purifier.md)**
-- **[Room Automation](packages/room_automation.md)**
-- **[Scenes](packages/scenes.md)**
-- **[Shelly 3EM](packages/shelly_3em.md)**
-- **[Smart Notifications](packages/smart_notifications.md)**
+## Catalogs
+
+- **[Dashboard Catalog](dashboards/index.md)**:
+  Visual overview of all Lovelace dashboards and views.
+
+- **[Package Catalog](packages/index.md)**:
+  Index of all feature-based configuration packages (Automations, Scripts, etc.).
 
 ## Contents
-- **[Automations](automations.md)**: Detailed breakdown of `packages/` automations.
-- **[Dashboards](dashboards.md)**: Overview of Lovelace dashboards and views.
+- **[Automations](automations.md)**: Detailed breakdown of UI-managed automations (`automations.yaml`).
+- **[Dashboards](dashboards/index.md)**: Overview of Lovelace dashboards.
+- **[Packages](packages/index.md)**: Modular configuration bundles.

docs/smart-home/packages/index.md

@@ -0,0 +1,47 @@
+---
+tags:
+  - package
+  - index
+  - automated
+---
+
+# Package Catalog
+
+Use this catalog to browse all installed configuration packages. Each package is a self-contained unit of functionality.
+
+!!! info "Auto-Generated"
+    This catalog is automatically maintained by the Documentation Agent.
+
+## 📦 Installed Packages
+-   **[Airthings](./airthings.md)**
+    <br> :material-arrow-right-bottom: *Normalizes Airthings Wave sensors (Temp, Humidity, CO2)*
+-   **[Aqara W500](./aqara_w500.md)**
+    <br> :material-arrow-right-bottom: *Manages temperature settings and schedules for the Bathroom Floor Heat (Aqara W500 Climate). Includes logic for high electricity price reduction and shower occupancy boost.*
+-   **[Car](./car.md)**
+    <br> :material-arrow-right-bottom: *Unified logic for Mercedes GLC. Normalizes sensors (Windows/Doors), wrapper switches, and Status Notifications.*
+-   **[Dishwasher](./dishwasher.md)**
+    <br> :material-arrow-right-bottom: *Logic, sensors, flags, and automations for the LG Dishwasher. Handles normalization of LG ThinQ data, maintenance reminders, and leak detection.*
+-   **[Dna Tv Hub](./dna_tv_hub.md)**
+    <br> :material-arrow-right-bottom: *Template switch for DNA TV Hub remote control*
+-   **[Garmin](./garmin.md)**
+    <br> :material-arrow-right-bottom: *Placeholder for Garmin integration*
+-   **[Home Time Modes](./home_time_modes.md)**
+    <br> :material-arrow-right-bottom: *Parametric Time-of-Day Logic*
+-   **[Nordpool Prices](./nordpool_prices.md)**
+    <br> :material-arrow-right-bottom: *Nordpool energy price calculations and logic*
+-   **[Office. Pc](./office._pc.md)**
+    <br> :material-arrow-right-bottom: *Office PC control (Audio, Displays, Power)*
+-   **[Office PC](./office_pc.md)**
+    <br> :material-arrow-right-bottom: **No description provided.**
+-   **[Philips Air Purifier](./philips_air_purifier.md)**
+    <br> :material-arrow-right-bottom: *Normalizes Philips Air Purifier attributes (PM2.5, Filters)*
+-   **[Room Automation](./room_automation.md)**
+    <br> :material-arrow-right-bottom: *Dynamic creation of room lighting settings via MQTT*
+-   **[Scenes](./scenes.md)**
+    <br> :material-arrow-right-bottom: *Definitions for various lighting scenes (Daylight, Night, Movie, etc.)*
+-   **[Shelly 3Em](./shelly_3em.md)**
+    <br> :material-arrow-right-bottom: *Power aggregation for Shelly 3EM (Total Power, Energy)*
+-   **[Smart Notifications](./smart_notifications.md)**
+    <br> :material-arrow-right-bottom: *Helpers and logic for the dynamic notification router*
+-   **[Unifi Access](./unifi_access.md)**
+    <br> :material-arrow-right-bottom: *Unified management for G4 Doorbell Pro Fingerprint & NFC.*

docs/smart-home/structure.md

@@ -1,60 +1,70 @@
+---
+tags:
+  - structure
+  - configuration
+  - automated
+---
+
 # Configuration & Structure
 
 ## Directory Structure
-
 An overview of the key directories and files in the Home Assistant root folder.
 
 | Directory / File | Purpose |
 | :--- | :--- |
+| **`.ag_scripts/`** | Automation scripts for maintaining this documentation and workspace. |
 | **`.storage/`** | Internal Home Assistant storage for registries (devices, entities, etc.). **Do not edit manually.** |
+| **`AI_CONTEXT.md`** |  |
+| **`ag_v2_agent.py`** |  |
+| **`ag_v2_dashboard.py`** |  |
+| **`ag_v2_package.py`** |  |
+| **`ag_v2_update.py`** |  |
+| **`automations.yaml`** | The main file for storing automations, commonly managed via the UI. |
 | **`blueprints/`** | Stores automation blueprints downloaded or created for reusability. |
 | **`button_card_templates/`** | Custom templates for `custom:button-card` Lovelace cards. |
+| **`configuration.yaml`** | The main configuration file for Home Assistant. |
 | **`custom_components/`** | Custom integrations installed manually or via HACS. |
 | **`custom_templates/`** | Global Jinja2 templates (macros) available throughout Home Assistant. |
+| **`debug_regex.py`** |  |
 | **`deps/`** | Python dependencies installed by Home Assistant or integrations. |
 | **`docs_site/`** | This documentation repository and MkDocs site structure. |
 | **`esphome/`** | ESPHome configuration YAML files and compilation artifacts (binaries). |
+| **`home-assistant-wakewords-collection-main/`** | Directory. |
+| **`home-assistant.log.fault`** |  |
+| **`home-assistant_v2.db`** |  |
+| **`home-assistant_v2.db-shm`** |  |
+| **`home-assistant_v2.db-wal`** |  |
+| **`image/`** | Directory. |
 | **`include/`** | Split configuration files referenced from `configuration.yaml` to keep it clean. |
 | **`model_cache/`** | Cache for local AI models (Wake words, assist pipelines). |
 | **`node-red/`** | Storage for Node-RED flows and settings (if the add-on is used). |
 | **`packages/`** | Configuration split into logical "packages" (bundling automations, scripts, configuration by feature). |
 | **`pyscript/`** | Python scripts and apps for the `pyscript` integration. |
+| **`scenes.yaml`** | Configuration file for defining scenes. |
+| **`scripts.yaml`** | Configuration file for scripts (sequences of actions). |
+| **`secrets.yaml`** | Stores sensitive data (passwords, tokens) referenced via `!secret`. |
 | **`themes/`** | Frontend themes definition files. |
-| **`tts/`** | Text-to-speech cache or configuration. |
+| **`tts/`** | Text-to-Speech cache or configuration. |
 | **`www/`** | Publicly accessible folder mapped to `/local/` for hosting custom cards, images, and resources. |
 | **`zigbee2mqtt/`** | Zigbee2MQTT data directory containing configuration and database. |
 | **`zigbee2mqtt-2/`** | Secondary Zigbee2MQTT instance data directory. |
-| **`automations.yaml`** | The main file for storing automations, commonly managed via the UI. |
-| **`configuration.yaml`** | The main configuration file for Home Assistant. |
-| **`scenes.yaml`** | Configuration file for defining scenes. |
-| **`scripts.yaml`** | Configuration file for scripts (sequences of actions). |
-| **`secrets.yaml`** | Stores sensitive data (passwords, tokens) referenced via `!secret`. |
 
 ---
 
 ## Configuration.yaml
-
 Below is the current content of `configuration.yaml` with explanations for each section.
 
 ```yaml
-# Core Home Assistant configuration
-# Defines unit system, time zone, and package loading.
 homeassistant:
   unit_system: metric
   time_zone: Europe/Helsinki
   ## Packages ##
-  # 'packages' allows us to split configuration by feature 
-  # (including automations, scripts, etc. in one file/folder)
   packages: !include_dir_named packages
 
-# Loads the default set of integrations (Map, History, Logbook, etc.). 
-# Essential for a standard experience.
+# Loads default set of integrations. Do not remove.
 default_config:
 
 ## NEEDED FOR TRAEFIK
-# HTTP configuration triggers the HTTP server integration.
-# 'use_x_forwarded_for' and 'trusted_proxies' are required when running 
-# behind a reverse proxy (like Traefik) to correctly identify client IPs.
 http:
   use_x_forwarded_for: true
   trusted_proxies:
@@ -63,41 +73,28 @@ http:
     - 127.0.0.1
 
 ## THEMES ##
-# Configures the Lovelace frontend.
-# Currently set to include themes from the 'themes' directory (commented out).
 frontend:
   #themes: !include_dir_merge_named themes
 
 ## TEXT TO SPEECH ##
-# Configures the Text-to-Speech (TTS) integration.
-# Using Google Translate platform for voice synthesis.
 tts:
   - platform: google_translate
 
-# Recorder handles storing data in the database (home-assistant_v2.db).
-# Configured here to potentially exclude specific entities from history.
 recorder:
 #  exclude:
 #    entities:
 
 ## HACS - PYSCRIPT ##
-# Pyscript integration allows writing automations in Python.
-# Configuration is split into 'include/pyscript.yaml'.
 pyscript: !include include/pyscript.yaml
 
 ## PowerCal
-# Powercalc integration estimates power consumption for non-smart devices.
-# Configuration is split into 'include/powercalc.yaml'.
 powercalc: !include include/powercalc.yaml
 
 ## CUSTOM/HACS - PHILIPS AIR PURIFIER ##
-# Fan domain configuration.
-# Specifically includes options for the Philips Air Purifier custom component.
 fan: !include include/philips_air_purifier.yaml
 
 ## FILES ##
-# Automations and Scripts files.
-# These are typically managed by the UI editors.
 automation: !include automations.yaml ## UI-managed
 script: !include scripts.yaml ## UI-managed
+
 ```