Docs: Update AI Summary with Deep Analysis (Architecture & Process)

Author: webosa

docs/smart-home/packages/ai_summary.md

@@ -16,14 +16,16 @@ version: Unknown
 
 ## Executive Summary
 <!-- START_SUMMARY -->
-This package acts as the **Frontend** and **Controller** for the external **[AI Log Reporter Integration](../integrations/ai_reporter.md)**.
-1.  It provides the **Template Sensor** to display the summary.
-2.  It handles the **Scheduling** (7:00 AM) and **SSH Connection** logic to trigger the remote analysis.
+The **AI Summary** package serves as the Home Assistant-side controller for the **[AI Log Reporter Integration](../integrations/ai_reporter.md)**. It manages the scheduling, triggering, and data ingestion of daily system reports generated by a remote AI agent. This package ensures that the heavy lifting of log analysis is offloaded to a dedicated Docker container while keeping the results fully integrated into the Home Assistant dashboard via native sensors and notifications.
 <!-- END_SUMMARY -->
 
 ## Process Description (Non-Technical)
 <!-- START_DETAILED -->
-*No detailed non-technical description generated yet.*
+This system runs automatically every morning at 7:00 AM.
+1.  **Trigger:** The system wakes up and sends a "Start" command to a remote server.
+2.  **Analysis:** The remote server (running a specialized AI Reporter) reads the logs from the past 24 hours. It looks for errors, warnings, and unusual patterns.
+3.  **Reporting:** Once finished, the remote server sends a summary back to Home Assistant.
+4.  **Notification:** You receive a notification on your phone (and a persistent message in the dashboard) summarizing the health of your smart home.
 <!-- END_DETAILED -->
 
 ## Dashboard Connections
@@ -33,22 +35,30 @@ This package acts as the **Frontend** and **Controller** for the external **[AI
 
 ## Architecture Diagram
 <!-- START_MERMAID_DESC -->
-The diagram below illustrates the hand-off between this Home Assistant package and the external Docker container. For full implementation details of the remote system, see the **[AI Reporter Integration](../integrations/ai_reporter.md)** documentation.
+The sequence diagram below details the interaction between the local Home Assistant instance and the remote **AI Log Reporter**. The process is initiated by a time-based trigger (7:00 AM) or a manual script invocation. Home Assistant opens a secure SSH tunnel to the remote host (`10.0.0.23`) and executes a Docker command (`docker exec`). The `ai-log-reporter` container processes the logs and, upon completion, fires an asynchronous event (`update_ai_summary`) back to the Home Assistant API. This event payload is captured by a Template Trigger, which updates the permanent `sensor.daily_system_summary`.
 <!-- END_MERMAID_DESC -->
 
 <!-- START_MERMAID -->
 ```mermaid
 sequenceDiagram
     participant Sched as ⏰ Schedule
-    participant Script as 📜 Script
+    participant Script as 📜 Script: run_ai_summary_now
     participant SSH as 🔐 SSH Tunnel
-    participant Remote as 📦 Remote Integration
+    participant Remote as 📦 Docker: ai-log-reporter
+    participant API as 📡 HA API
+    participant Sensor as 🧠 Sensor: daily_system_summary
 
     Sched->>Script: Trigger 7:00 AM
-    Script->>SSH: Connect root@10.0.0.23
-    SSH->>Remote: Trigger Docker Analysis
-    Note over Remote: Processing...
-    Remote-->>Script: (Async Event Return)
+    Script->>SSH: ssh root@10.0.0.23 (Exec Reporter)
+    activate SSH
+    SSH->>Remote: docker exec python /app/reporter.py
+    activate Remote
+    Note right of Remote: Analyze Logs...
+    Remote->>API: POST /api/events/update_ai_summary
+    API->>Sensor: Event: update_ai_summary
+    deactivate Remote
+    SSH-->>Script: Exit Code 0
+    deactivate SSH
 ```
 <!-- END_MERMAID -->