Update docs

Author: webosa

AI_CONTEXT.md

@@ -59,7 +59,23 @@ 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)
+
+*This section captures 'Silent Knowledge' and lessons learned.*
+
+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.
+
+2. **ADR-002: Dashboard Generation via Python:**
+   * **Failure:** Using LLMs to "rewrite" JSON dashboards often results in broken YAML or single-line dumps.
+   * **Decision:** We rely on `ag_regenerate_dashboards.py`. This script forces `default_flow_style=False` to ensure readable, block-style YAML output. It also enforces privacy redaction programmatically.
+
+3. **ADR-003: Samba & Git Ownership:**
+   * **Issue:** Windows clients accessing HA via Samba see "Dubious Ownership" errors because the files are owned by `root` on the server.
+   * **Fix:** We enforce `git config --global --add safe.directory '*'` on all dev machines.
+
+4. **ADR-004: MkDocs Material Features:**
+   * **Decision:** We explicitly enable `navigation.indexes` (folders act as pages) and `admonition` extensions to support high-quality CMDB layouts.

docs/system_manual/setup_guide.md

@@ -1,6 +1,6 @@
 # EvisHomeLab: Documentation System Manual
 
-**Version:** 2.4
+**Version:** 2.5
 **Philosophy:** Agentic CMDB (Configuration Management Database)
 **Strategy:** "Detached Docs" (Private Config -> Public Documentation)
 
@@ -15,7 +15,7 @@ This project automates the documentation of a Home Assistant Smart Home and Home
 
 ---
 
-## PART A: One-Time Initialization (The Genesis)
+# PART A: One-Time Initialization (The Genesis)
 
 **⚠️ STOP:** Only perform these steps if you are setting up the system **for the very first time** on a fresh Home Assistant server. If the system already exists and you just want to connect a new laptop, skip to **PART B**.
 
@@ -131,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.).
 
@@ -173,7 +173,7 @@ 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 Full Maintenance Cycle (Recommended Routine)
 Run this sequence to update everything cleanly.
@@ -212,14 +212,25 @@ You must "hydrate" the AI with the project context so it can act as the Architec
 > 5. **Visuals:** Insert a placeholder link for a screenshot (e.g., `![View](assets/images/heating.png)`).
 > Finally, update `mkdocs.yml` navigation."
 
+**Task: Web Design & Image Management**
+> "I have added new images to `docs_site/docs/assets/images/` and I want to update the styling.
+>
+> **Task 1 (Images):** Scan the `images` folder. Update the Markdown files to replace placeholder text with the actual image links.
+>
+> **Task 2 (CSS):** Check `docs_site/docs/assets/css/custom.css`. Ensure it is linked in `mkdocs.yml`. If I ask for color changes, apply them to the CSS variables."
+
 **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: 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, convert everything to clean YAML, and update `dashboards.md`."
+
 ---
 
-## PART D: Troubleshooting
+# PART D: Troubleshooting
 
 ### 1. `mkdocs.yml` is Red
 * **Status:** False Positive. Ignore it.