Update docs

Author: webosa

AI_CONTEXT.md

@@ -1,6 +1,6 @@
 # AI Persona & Project Context: EvisHomeLab
 
-**Role:** You are the Lead Architect and Technical Writer for EvisHomeLab.
+**Role:** You are the Lead Architect, Technical Writer, and Web Designer for EvisHomeLab.
 **Primary Goal:** Maintain a high-quality, automated CMDB (Configuration Management Database) for a Home Assistant setup.
 
 ## 1. The Architecture (Mental Model)
@@ -31,22 +31,16 @@ We operate on a **"Detached Docs"** strategy to ensure security:
 
 * **Structure:** Follow the CMDB hierarchy (`docs/smart-home/packages/`, `docs/smart-home/dashboards.md`).
 
-* **Visuals:**
-
-  * Use **Mermaid JS** sequence diagrams for logic flow.
-
-  * Do NOT generate fake HTML/CSS UI simulations.
-
-  * Use placeholder image links: `![View Name](assets/images/placeholder.png)`.
+* **Visuals (Web Designer Role):**
+  * **Mermaid JS:** Use sequence diagrams for logic flow.
+  * **No Fakes:** Do NOT generate fake HTML/CSS UI simulations.
+  * **Screenshots:** Use the "Drop & Link" method. Place real screenshots in `assets/images/` and link them in Markdown.
+  * **Styling:** Use Admonitions (`!!! info`) for architectural notes.
 
 * **Format:**
-
   * **YAML Conversion:** When converting JSON (dashboards) to YAML, ensure **multi-line formatting** with 2-space indentation. NEVER output single-line object dumps.
-
   * Use Standard YAML code blocks for configuration.
 
-  * Use Admonitions (`!!! info`) for architectural notes.
-
 ## 4. Coding Standards for Scripts
 
 When creating Python or Shell scripts for this project:
@@ -65,9 +59,7 @@ When creating Python or Shell scripts for this project:
 ## 5. Deployment Logic
 
 * The site is built via **GitHub Actions**.
-
 * We must push changes from the `docs_site/` directory to trigger a build.
-
 * **CNAME:** Ensure `docs/CNAME` exists and contains `www.evishome.com`.
 
 ## 6. Project History & Architectural Decisions (ADRs)
@@ -76,7 +68,6 @@ When creating Python or Shell scripts for this project:
 
 1. **ADR-001: Detached Documentation:**
    * **Decision:** We use two separate Git repositories. The root `/config` is local-only to prevent accidental secret leakage. Only `docs_site/` is pushed to GitHub.
-   * **Why:** Home Assistant config contains too many sensitive files (secrets, logs, backups) to safely manage in a public repo without complex git-crypt setups.
 
 2. **ADR-002: Dashboard Generation via Python:**
    * **Failure:** Using LLMs to "rewrite" JSON dashboards often results in broken YAML or single-line dumps.

docs/system_manual/setup_guide.md

@@ -1,6 +1,6 @@
 # EvisHomeLab: Documentation System Manual
 
-**Version:** 1.9
+**Version:** 2.4
 **Philosophy:** Agentic CMDB (Configuration Management Database)
 **Strategy:** "Detached Docs" (Private Config -> Public Documentation)
 
@@ -84,15 +84,14 @@ CRITICAL RULES:
 
 ### 3. Bootstrap Helper Tools
 
-We rely on Python scripts to manage complex tasks. Create these files in your root folder:
+We rely on Python scripts to manage complex tasks. We have a master script that generates them.
 
 **A. Create `ag_update_docs.py`**
-* **Purpose:** Updates this manual and the AI Context.
+* **Purpose:** The Master Installer. Updates this manual, the AI Context, and the dashboard tools.
 * **How:** Ask the Agent: "Create `ag_update_docs.py` with the content provided in the System Manual Part A." (See repository history for source).
 
-**B. Create `ag_regenerate_dashboards.py`**
-* **Purpose:** Converts JSON dashboards to YAML documentation.
-* **How:** Ask the Agent: "Create `ag_regenerate_dashboards.py` that reads `.storage/lovelace_dashboards`, redacts names, and outputs clean YAML blocks."
+**B. Run it:**
+* Run `python ag_update_docs.py` to auto-generate `ag_regenerate_dashboards.py`.
 
 ### 4. Scaffold Documentation Site
 
@@ -132,7 +131,7 @@ git push -u origin main
 
 ---
 
-# PART B: Workstation Setup (Adding Laptops)
+## PART B: Workstation Setup (Adding Laptops)
 
 **✅ START HERE:** If the system is already running and you want to work on it from a new computer (Laptop 2, 3, etc.).
 
@@ -174,11 +173,22 @@ These settings are stored on your laptop, not the server, so you must set them a
 
 ---
 
-# PART C: Daily Operations (The Workflow)
+## PART C: Daily Operations (The Workflow)
 
-### 1. The AI Architect Workflow (Start Here)
-This system relies on a two-tier workflow: **Architect (Chat)** vs **Builder (Agent)**.
+### 1. The Full Maintenance Cycle (Recommended Routine)
+Run this sequence to update everything cleanly.
 
+1.  **Update Tools:** Run `python ag_update_docs.py` (Ensures you have the latest manual and scripts).
+2.  **Regenerate Dashboards:** Run `python ag_regenerate_dashboards.py` (Scans HA, redacts names, writes Markdown).
+3.  **Publish:**
+    ```bash
+    cd docs_site
+    git add .
+    git commit -m "Routine documentation update"
+    git push
+    ```
+
+### 2. The AI Architect Workflow
 **When starting a new Chat Session with an AI Model (like Gemini):**
 You must "hydrate" the AI with the project context so it can act as the Architect. Paste this prompt:
 
@@ -190,10 +200,7 @@ You must "hydrate" the AI with the project context so it can act as the Architec
 >
 > **Action:** Confirm you have loaded the context and are ready to assist with maintaining the CMDB."
 
-*(Then upload/paste the content of those two files).*
-
-### 2. The Agent Workflow (Execution)
-Once the Architect (Chat) designs a prompt, paste it into the Antigravity Agent Panel to execute it.
+### 3. The Agent Workflow (Execution)
 
 **Task: Generate Package Documentation**
 > "Perform a deep architectural scan of my `packages/` directory.
@@ -205,40 +212,19 @@ Once the Architect (Chat) designs a prompt, paste it into the Antigravity Agent
 > 5. **Visuals:** Insert a placeholder link for a screenshot (e.g., `![View](assets/images/heating.png)`).
 > Finally, update `mkdocs.yml` navigation."
 
-**Task: Convert Dashboard to YAML (Python Method)**
-> "Run `python ag_regenerate_dashboards.py` in the terminal.
-> This script will read the raw JSON dashboards, apply strict privacy redaction (Jukka->Evis, etc.), convert everything to clean YAML, and update `dashboards.md`."
-
 **Task: Update Structure Documentation**
 > "Update `docs_site/docs/smart-home/structure.md`.
 > 1. Re-scan the root directory and update the file tree structure description (Folders first, then files).
 > 2. Read `configuration.yaml` and update the commented code block explanation."
 
-**Task: Publish This System Manual**
-> "Copy `EvisHomeLab_Setup_Guide.md` (from Root) to `docs_site/docs/system_manual/setup_guide.md`.
-> Ensure `docs_site/mkdocs.yml` has a navigation entry called **'System Manual'** pointing to `system_manual/setup_guide.md`."
-
-### 3. Publishing to the Web
-When documentation updates are complete:
-```bash
-cd docs_site
-git add .
-git commit -m "Update docs"
-git push
-```
-
 ---
 
-# PART D: Troubleshooting
+## PART D: Troubleshooting
 
 ### 1. `mkdocs.yml` is Red
-If you see a red error on the line: `format: !!python/name:pymdownx...`
-* **Status:** False Positive.
-* **Explanation:** The text editor doesn't understand the `!!python` tag, but the MkDocs build system does.
-* **Action:** Ignore it. It will deploy correctly.
+* **Status:** False Positive. Ignore it.
 
 ### 2. "Unsafe Repository" Error
-If Git complains about ownership:
 * **Run:** `git config --global --add safe.directory '*'` in the terminal.
 
 ### 3. Website shows 404