Update docs

webosa · webosa · commit 669ef387bc8a · 2025-12-07T14:41:45.000+02:00
diff --git a/AI_CONTEXT.md b/AI_CONTEXT.md
@@ -85,4 +85,4 @@ When creating Python or Shell scripts for this project:
    * **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.
+   * **Decision:** We explicitly enable `navigation.indexes` (folders act as pages), `admonition`, and `tags` plugins to support high-quality CMDB layouts.
diff --git a/AI_CONTEXT.md.1765111281.bak b/AI_CONTEXT.md.1765111281.bak
@@ -0,0 +1,88 @@
+# AI Persona & Project Context: 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)
+
+We operate on a **"Detached Docs"** strategy to ensure security:
+
+1. **Private Config (Local):** The root `/config` folder. Contains live YAML/JSON. NEVER pushed to public Git.
+
+2. **Public Docs (Remote):** The `/config/docs_site` folder. Contains MkDocs Markdown. Pushed to `github.com/EvisHome/EvisHomeLab`.
+
+## 2. Critical Safety Rules (Non-Negotiable)
+
+1. **Read-Only Zones:** You may READ `.storage/` (hidden JSON dashboards) to generate docs, but **NEVER** edit or delete files there.
+
+2. **Asset Safety:** Never delete the `www/` folder or `packages/` folder.
+
+3. **Secret Redaction:** When embedding code blocks, ALWAYS replace `!secret wifi_password` with `!secret [REDACTED]`.
+
+4. **Privacy & Name Redaction (STRICT):** You must replace ALL occurrences of family names, **including lowercase variants** found in code variables or entity IDs.
+   
+   * 'Jukka' OR 'jukka' -> 'Evis'
+   * 'Alisa' OR 'alisa' -> 'Daughter'
+   * 'Piia' OR 'piia' -> 'Grandma'
+   * 'Elias' OR 'elias' -> 'Grandpa'
+   * 'Anton' OR 'anton' -> 'Guest'
+
+## 3. Documentation Style Guide
+
+* **Structure:** Follow the CMDB hierarchy (`docs/smart-home/packages/`, `docs/smart-home/dashboards.md`).
+
+* **Metadata (Tags):**
+  * All Markdown files should start with YAML Frontmatter.
+  * **Locking:** If a file contains `auto_update: false`, **DO NOT EDIT IT**.
+  * **Tags:** Use `tags: [category, status]` (e.g., `tags: [package, manual]`).
+
+* **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.
+    * Dashboard Views -> `assets/images/dashboards/`
+    * Package Cards -> `assets/images/packages/`
+  * **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.
+
+## 4. Coding Standards for Scripts
+
+When creating Python or Shell scripts for this project:
+
+1. **Naming Convention:** All helper tools must start with `ag_` (e.g., `ag_regenerate_dashboards.py`).
+2. **File Headers:** Every script must begin with a standard comment block:
+   ```python
+   # -----------------------------------------------------------------------------
+   # File: [filename]
+   # Version: [version]
+   # Description: [short summary]
+   # Usage: [command to run]
+   # -----------------------------------------------------------------------------
+   ```
+
+## 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.
diff --git a/docs/system_manual/setup_guide.md b/docs/system_manual/setup_guide.md
@@ -1,6 +1,6 @@
 # EvisHomeLab: Documentation System Manual
 
-**Version:** 3.9
+**Version:** 5.0
 **Philosophy:** Agentic CMDB (Configuration Management Database)
 **Strategy:** "Detached Docs" (Private Config -> Public Documentation)
 
@@ -86,13 +86,12 @@ CRITICAL RULES:
 
 We rely on Python scripts to manage complex tasks.
 
-**A. `ag_update_docs.py` (The Architect's Tool)**
-* **Purpose:** The Source of Truth. Updates this manual, the AI Context, and scripts.
-* **Usage:** Run `python ag_update_docs.py` whenever you update the system design.
+**A. Create `ag_update_docs.py`**
+* **Purpose:** The Master Installer. Updates this manual, the AI Context, and the dashboard tools.
+* **How:** Copy the content from the repository history or backup.
 
-**B. `ag_regenerate_dashboards.py` (The Formatter)**
-* **Purpose:** Converts JSON dashboards to YAML and links screenshots.
-* **Usage:** Run `python ag_regenerate_dashboards.py` to refresh dashboard docs.
+**B. Run it:**
+* Run `python ag_update_docs.py` to auto-generate `ag_regenerate_dashboards.py`.
 
 ### 4. Scaffold Documentation Site
 
@@ -176,11 +175,46 @@ These settings are stored on your laptop, not the server, so you must set them a
 
 ---
 
-## PART C: Daily Operations (The Workflow)
+## PART C: Core Features & Concepts
 
-### 1. The Full Maintenance Cycle
-1.  **Update Tools:** `python ag_update_docs.py`
-2.  **Regenerate Dashboards:** `python ag_regenerate_dashboards.py`
+### 1. Visual Assets Standard
+When adding images, you **must** use the correct naming convention so the automation scripts can find them.
+
+| Type | Folder Location | Naming Convention |
+| :--- | :--- | :--- |
+| **Dashboards** | `docs/assets/images/dashboards/` | `view_[path].png` (e.g. `view_kitchen.png`) |
+| **Packages** | `docs/assets/images/packages/` | `[package_name].png` (e.g. `heating.png`) |
+| **General** | `docs/assets/images/brand/` | Free choice |
+
+### 2. Locking Files (Prevent Overwrite)
+If you have heavily customized a documentation page and don't want the Agent to touch it again:
+* Add this to the very top of the Markdown file:
+  ```yaml
+  ---
+  auto_update: false
+  ---
+  ```
+* The Agent is instructed to check for this flag and abort if found.
+
+### 3. Tagging Strategy
+We use YAML frontmatter to categorize pages. This enables Tag Clouds on the website.
+* **Standard Tags:** `package`, `dashboard`, `network`, `automated`, `manual`.
+* **Example:**
+  ```yaml
+  ---
+  tags:
+    - package
+    - automated
+  ---
+  ```
+
+---
+
+## PART D: Daily Operations (The Workflow)
+
+### 1. The Full Maintenance Cycle (Recommended Routine)
+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
@@ -201,24 +235,17 @@ Paste this prompt to "hydrate" the AI with the project context:
 >
 > **Action:** Confirm you have loaded the context and are ready to assist with maintaining the CMDB."
 
-### 3. Visual Assets Standard
-When adding images, you **must** use the correct naming convention so the automation scripts can find them.
-
-| Type | Folder Location | Naming Convention |
-| :--- | :--- | :--- |
-| **Dashboards** | `docs/assets/images/dashboards/` | `view_[path].png` (e.g. `view_kitchen.png`) |
-| **Packages** | `docs/assets/images/packages/` | `[package_name].png` (e.g. `heating.png`) |
-| **General** | `docs/assets/images/brand/` | Free choice |
-
-### 4. The Agent Prompts
+### 3. The Agent Workflow (Execution Prompts)
 
 **Task: Update Single Package (Focus Mode)**
 > "Update the documentation for the **[PACKAGE_NAME]** package.
 > 1. Read `packages/[PACKAGE_NAME].yaml`.
 > 2. Find/Create `docs_site/docs/smart-home/packages/[PACKAGE_NAME].md`.
-> 3. **Update Content:** Logic Summary & Mermaid Diagram.
-> 4. **Dashboard Links:** Scan `.storage/lovelace_dashboards` for cards using these entities and embed them.
-> 5. **Visuals:** Look in `assets/images/packages/` for an image named `[PACKAGE_NAME].png` or `[PACKAGE_NAME]_card.png`. If found, display it. If not, use a placeholder."
+> 3. **Check Metadata:** Read the top of the Markdown file. If it contains `auto_update: false`, **ABORT**.
+> 4. **Update Content:** Logic Summary & Mermaid Diagram.
+> 5. **Dashboard Links:** Scan `.storage/lovelace_dashboards` for cards using these entities and embed them.
+> 6. **Visuals:** Look in `assets/images/packages/` for an image named `[PACKAGE_NAME].png`.
+> 7. **Tags:** Ensure frontmatter includes `tags: [package, automated]`."
 
 **Task: Generate All Package Documentation (Full Scan)**
 > "Perform a deep architectural scan of my `packages/` directory.
@@ -236,17 +263,30 @@ When adding images, you **must** use the correct naming convention so the automa
 > 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: Enable Tags & Tag Cloud**
-> "Edit `docs_site/mkdocs.yml`.
-> 1. Under `plugins:`, add `- tags`.
-> 2. Commit changes: 'Enable MkDocs Tags plugin'."
-
 **Task: Convert Dashboard to YAML**
 > "Run `python ag_regenerate_dashboards.py`."
 
 ---
 
-## PART D: Troubleshooting
+## PART E: Tool Reference
+
+### 1. `ag_update_docs.py` (The Master Installer)
+* **What it is:** A Python script containing the entire System Manual and AI Context as text strings.
+* **When to run:** Every time you start a work session, or after you have modified the manual in the Chat.
+* **Function:** It overwrites the documentation files on disk to ensure they match the latest Architect decisions. It includes a backup mechanism (`.bak`) to prevent accidental data loss.
+
+### 2. `ag_regenerate_dashboards.py` (The Privacy Engine)
+* **What it is:** A specialized script that parses Home Assistant's hidden JSON dashboard database.
+* **When to run:** After you make changes to your Lovelace dashboard in the Home Assistant UI.
+* **Function:**
+    * Reads `.storage/lovelace_dashboards`.
+    * Performs **Case-Insensitive Redaction** of family names (e.g., Jukka -> Evis).
+    * Converts the JSON into **Clean, Block-Style YAML** for readability.
+    * Generates `dashboards.md` with screenshot placeholders pre-linked.
+
+---
+
+## PART F: Troubleshooting
 
 ### 1. `mkdocs.yml` is Red
 * **Status:** False Positive. Ignore it.
diff --git a/docs/system_manual/setup_guide.md.1765111281.bak b/docs/system_manual/setup_guide.md.1765111281.bak
