Apply strict privacy redaction to dashboards

Author: webosa

AI_CONTEXT.md

@@ -19,17 +19,13 @@ We operate on a **"Detached Docs"** strategy to ensure security:
 
 3. **Secret Redaction:** When embedding code blocks, ALWAYS replace `!secret wifi_password` with `!secret [REDACTED]`.
 
-4. Person names reduction: When you find names from anywhere replace them as follows:
-
-   * 'Jukka' -> 'Evis'
-
-   * 'Alisa' -> 'Daughter'
-
-   * 'Piia' -> 'Grandma'
-
-   * 'Elias' -> 'Grandpa'
-
-   * 'Anton' -> 'Guest'
+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
 
@@ -45,21 +41,26 @@ We operate on a **"Detached Docs"** strategy to ensure security:
 
 * **Format:**
 
-  * **YAML Conversion:** When converting JSON (dashboards) to YAML, ensure **multi-line formatting** with 2-space indentation. NEVER output single-line object dumps or PowerShell artifacts (e.g. `@{...}`).
+  * **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. Standard Operating Procedures (SOPs)
-
-Refer to **`docs/system_manual/setup_guide.md`** for the specific prompts to run for:
-
-* Generating Package Documentation.
+## 4. Coding Standards for Scripts
 
-* Converting Dashboards to YAML.
+When creating Python or Shell scripts for this project:
 
-* Updating the System Structure.
+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
 
@@ -68,3 +69,22 @@ Refer to **`docs/system_manual/setup_guide.md`** for the specific prompts to run
 * 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.
+   * **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.
+   * **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:** 1.7
+**Version:** 1.9
 **Philosophy:** Agentic CMDB (Configuration Management Database)
 **Strategy:** "Detached Docs" (Private Config -> Public Documentation)
 
@@ -70,7 +70,7 @@ Open Antigravity connected to `/config` and run this prompt in the Agent:
 >
 > 3. Commit the current state with the message 'Initial Home Assistant Backup'."
 
-### 2. Establish Agent Rules (The Hard Constraints)
+### 2. Establish Agent Rules
 
 Create a file at `.antigravity/rules.md` in the root:
 
@@ -82,7 +82,19 @@ CRITICAL RULES:
 4. **Context & Persona:** Always consult `docs_site/AI_CONTEXT.md` for documentation standards, visual styles, and privacy rules before writing documentation.
 ```
 
-### 3. Scaffold Documentation Site
+### 3. Bootstrap Helper Tools
+
+We rely on Python scripts to manage complex tasks. Create these files in your root folder:
+
+**A. Create `ag_update_docs.py`**
+* **Purpose:** Updates this manual and the AI Context.
+* **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."
+
+### 4. Scaffold Documentation Site
 
 Paste this prompt into the Agent:
 
@@ -100,15 +112,11 @@ Paste this prompt into the Agent:
 >
 > 3. Create a file `docs_site/docs/CNAME` containing: `www.evishome.com`"
 
-### 4. Initialize AI Context (The Brain)
-
-Paste this prompt to create the "Memory" file for the Agent:
+### 5. Initialize AI Context
 
-> "Create a file `docs_site/AI_CONTEXT.md`.
-> Populate it with the Project Persona, Privacy Rules (Jukka->Evis), and Documentation Style Guide (Mermaid diagrams, YAML blocks).
-> This file will serve as the source of truth for all future Agent sessions."
+Run `python ag_update_docs.py` to generate the `AI_CONTEXT.md` file.
 
-### 5. Link Docs to GitHub
+### 6. Link Docs to GitHub
 
 Run these commands in the terminal:
 
@@ -168,10 +176,26 @@ These settings are stored on your laptop, not the server, so you must set them a
 
 # PART C: Daily Operations (The Workflow)
 
-### Task: Generate Package Documentation
+### 1. The AI Architect Workflow (Start Here)
+This system relies on a two-tier workflow: **Architect (Chat)** vs **Builder (Agent)**.
+
+**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:
+
+> "I am resuming work on the **EvisHomeLab** project.
+>
+> **Task:**
+> 1. Read the attached **`docs_site/AI_CONTEXT.md`** to load your Persona, Architecture constraints, and Safety Rules.
+> 2. Read the attached **`docs_site/docs/system_manual/setup_guide.md`** to understand the operational workflows.
+>
+> **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).*
 
-**Use when:** You have added a new package (e.g., `solar.yaml`) and want to document it.
+### 2. The Agent Workflow (Execution)
+Once the Architect (Chat) designs a prompt, paste it into the Antigravity Agent Panel to execute it.
 
+**Task: Generate Package Documentation**
 > "Perform a deep architectural scan of my `packages/` directory.
 > **For EVERY YAML file found, create a corresponding Markdown file in `docs_site/docs/smart-home/packages/` containing:**
 > 1. **Executive Summary:** What does this package do?
@@ -181,35 +205,21 @@ These settings are stored on your laptop, not the server, so you must set them a
 > 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)
-
-**Use when:** You have edited the Dashboard in the UI and want to update the docs. **Requires Python on your PC.**
-
-> "Write and execute a Python script to regenerate `docs_site/docs/smart-home/dashboards.md`.
-> 1. **Read Source:** Load `.storage/lovelace_dashboards`.
-> 2. **Parse & Convert:** Convert JSON to **Block-Style YAML** (`default_flow_style=False`).
-> 3. **Redact:** Apply name redaction rules (e.g., Jukka -> Evis) as per `AI_CONTEXT.md`.
-> 4. **Write Output:** Create headers for each view and embed the clean YAML code blocks."
-
-### Task: Update Structure Documentation
-
-**Use when:** You have added new top-level folders or changed `configuration.yaml`.
+**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
-
-**Use when:** You want to update this Setup Guide on the public website.
-
+**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`."
 
-### Publishing to the Web
-
+### 3. Publishing to the Web
 When documentation updates are complete:
-
 ```bash
 cd docs_site
 git add .