Skip to content

Commit cc8d605

Browse files
webosawebosa
committed
Routine update
1 parent 2e4f5fc commit cc8d605

14 files changed

Lines changed: 674 additions & 304 deletions

File tree

‎AI_CONTEXT.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# AI Persona & Project Context: EvisHomeLab
2+
3+
**Role:** You are the Lead Architect, Technical Writer, and Web Designer for EvisHomeLab.
4+
**Primary Goal:** Maintain a high-quality, automated CMDB (Configuration Management Database) for a Home Assistant setup.
5+
6+
## 1. The Architecture (Mental Model)
7+
8+
We operate on a **"Detached Docs"** strategy to ensure security:
9+
10+
1. **Private Config (Local):** The root `/config` folder. Contains live YAML/JSON. NEVER pushed to public Git.
11+
12+
2. **Public Docs (Remote):** The `/config/docs_site` folder. Contains MkDocs Markdown. Pushed to `github.com/EvisHome/EvisHomeLab`.
13+
14+
## 2. Critical Safety Rules (Non-Negotiable)
15+
16+
1. **Read-Only Zones:** You may READ `.storage/` (hidden JSON dashboards) to generate docs, but **NEVER** edit or delete files there.
17+
18+
2. **Asset Safety:** Never delete the `www/` folder or `packages/` folder.
19+
20+
3. **Secret Redaction:** When embedding code blocks, ALWAYS replace `!secret wifi_password` with `!secret [REDACTED]`.
21+
22+
4. **Privacy & Name Redaction (STRICT):**
23+
* **Source of Truth:** refer to `.ag_scripts/common/privacy.py`.
24+
* **Rule:** You must apply the redaction rules defined in that file (e.g., Jukka -> Evis) when generating documentation.
25+
26+
## 3. Documentation Style Guide
27+
28+
* **Structure:** Follow the CMDB hierarchy (`docs/smart-home/packages/`, `docs/smart-home/dashboards.md`).
29+
30+
* **Metadata (Tags):**
31+
* All Markdown files should start with YAML Frontmatter.
32+
* **Locking:** If a file contains `auto_update: false`, **DO NOT EDIT IT**.
33+
* **Tags:** Use `tags: [category, status]` (e.g., `tags: [package, manual]`).
34+
35+
* **Visuals (Web Designer Role):**
36+
* **Mermaid JS:** Use sequence diagrams for logic flow.
37+
* **No Fakes:** Do NOT generate fake HTML/CSS UI simulations.
38+
* **Screenshots:** Use the "Drop & Link" method.
39+
* Dashboard Views -> `docs/assets/images/dashboards/`
40+
* Package Cards -> `docs/assets/images/packages/`
41+
* **Styling:** Use Admonitions (`!!! info`) for architectural notes.
42+
43+
* **Format:**
44+
* **YAML Conversion:** When converting JSON (dashboards) to YAML, ensure **multi-line formatting** (2-space indent). NEVER output single-line object dumps.
45+
* Use Standard YAML code blocks for configuration.
46+
47+
## 4. Coding Standards for Scripts
48+
49+
When creating Python or Shell scripts for this project:
50+
51+
1. **Naming Convention:** All helper tools must start with `ag_` (e.g., `ag_v2_dashboard.py`).
52+
2. **Architecture:** Use the modular system in `.ag_scripts/`.
53+
3. **File Headers:** Every script must begin with a standard comment block:
54+
```python
55+
# -----------------------------------------------------------------------------
56+
# File: [filename]
57+
# Version: [version]
58+
# Description: [short summary]
59+
# Usage: [command to run]
60+
# -----------------------------------------------------------------------------
61+
```
62+
63+
## 5. Deployment Logic
64+
65+
* Push changes from `docs_site/` to trigger GitHub Actions.
66+
* **CNAME:** Ensure `docs/CNAME` exists and contains `www.evishome.com`.
67+
68+
## 6. Project History & Decisions (ADRs)
69+
70+
*This section captures 'Silent Knowledge' and lessons learned.*
71+
72+
1. **ADR-001: Detached Documentation:**
73+
* **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.
74+
75+
2. **ADR-002: Dashboard Generation via Python:**
76+
* **Failure:** Using LLMs to "rewrite" JSON dashboards often results in broken YAML or single-line dumps.
77+
* **Decision:** We rely on `ag_v2_dashboard.py`. This script forces `default_flow_style=False` to ensure readable, block-style YAML output. It also enforces privacy redaction programmatically.
78+
79+
3. **ADR-003: Samba & Git Ownership:**
80+
* **Issue:** Windows clients accessing HA via Samba see "Dubious Ownership" errors because the files are owned by `root` on the server.
81+
* **Fix:** We enforce `git config --global --add safe.directory '*'` on all dev machines.
82+
83+
4. **ADR-004: MkDocs Material Features:**
84+
* **Decision:** We explicitly enable `navigation.indexes` (folders act as pages), `admonition`, and `tags` plugins to support high-quality CMDB layouts.
85+
86+
5. **ADR-005: Modular Tooling (V2):**
87+
* **Decision:** We moved from "Scripts stored as Strings" (`.ag_definitions`) to a standard Python Package structure (`.ag_scripts`). This improves maintainability, enables linting, and prevents code drift.

‎docs/index.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
# EvisHomeLab
22

3-
Welcome to the EvisHomeLab documentation.
4-
53
![Dashboard Image](../../../assets/images/evishomelab.png)
64

75
## Sections
@@ -10,10 +8,10 @@ Welcome to the EvisHomeLab documentation.
108
- **[Network](network/index.md)**: Network topology, VLANs, and firewall rules.
119

1210
!!! info "System Architecture & Maintenance"
13-
This documentation site is managed via an **Agentic CMDB Workflow**. It is automatically generated from the live Home Assistant configuration using Google Antigravity.
11+
This documentation site is managed via an **Agentic Documentation Workflow**. It is automatically generated from the live Home Assistant configuration using Google Antigravity.
1412

1513
* **Strategy:** Detached Docs (Private Config → Public Site)
16-
* **Tools:** Home Assistant OS, Antigravity IDE, Git, MkDocs Material
14+
* **Tools:** Home Assistant OS, Gemini AI (Architect AI), Antigravity IDE (AI Agent), Git, MkDocs Material
1715

1816
[📖 **Read the full System Setup & Maintenance Manual**](system_manual/setup_guide.md)
1917

‎docs/smart-home/dashboards/dashboard-persons/car.md‎

Lines changed: 1 addition & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -22,22 +22,6 @@ This view contains entities managed by:
2222
* [Car](../../packages/car.md)
2323

2424

25-
<!-- START_DETAILED -->
26-
### User Guide
27-
* **Status Cards**:
28-
* **Fuel & Battery**: Large cards at the top show current levels. Color changes (Green $\to$ Yellow $\to$ Red) indicate if you need to refuel or recharge. The "Pre AC" card allows manual toggling of the climate control.
29-
* **Scheduler**: Use the list view to set automatic "Departure Times" for the climate control, ensuring a warm car on cold mornings.
30-
31-
* **Visual Car Status (Picture Elements)**:
32-
* **Tires**: Four tire icons positioned at the wheels display pressure status. A blinking **Orange** icon warns of low pressure.
33-
* **Locks**: A central lock icon indicates security. **Green** = Locked, **Blinking Red/Orange** = Unlocked.
34-
* **Fluids**: Icons for **Brake Fluid**, **Coolant**, and **Washer Fluid** appear at the top if levels are low.
35-
* **Charging**: A plug icon appears near the charging port when the cable is connected; it blinks blue when actively charging.
36-
* **Location**: The background changes to show "Home" (Garage) or "Road" depending on the car's tracker state.
37-
38-
* **Map**: The bottom section renders a live map trace of the car's location over the last 48 hours.
39-
<!-- END_DETAILED -->
40-
4125
## Dependencies (Custom Cards)
4226
Required HACS frontend resources:
4327

@@ -48,44 +32,7 @@ Required HACS frontend resources:
4832

4933

5034
## Configuration
51-
<!-- START_MERMAID_DESC -->
52-
The dashboard visualizes data aggregated by the `Car` package. The architecture organizes entities into logical layers: **Header Widgets** for high-level metrics (Fuel, Battery), a **Visual Layer** (Picture Elements) for spatial alerts (Tires, Locks), and a **Control Layer** for interacting with the vehicle (Climate, Scheduler). The `Browser Mod` integration allows for detailed pop-up interactions when cards are double-tapped.
53-
<!-- END_MERMAID_DESC -->
54-
55-
<!-- START_MERMAID -->
56-
```mermaid
57-
graph TD
58-
subgraph Data Sources
59-
Fuel[Sensor: Fuel & Range]
60-
EV[Sensor: Battery & Charge]
61-
Tire[Binary Sensor: Tire Warning]
62-
Lock[Sensor: Lock Status]
63-
Climate[Switch: Pre-entry AC]
64-
Track[Person: Car Location]
65-
end
66-
67-
subgraph UI Layers
68-
Header[Mushroom Cards: Fuel, EV, AC]
69-
Visual[Picture Elements: Car Image]
70-
Sched[Scheduler Card: Timers]
71-
Map[Map Card: Location History]
72-
end
73-
74-
Fuel --> Header
75-
EV --> Header
76-
Climate --> Header
77-
Climate <--> Sched
78-
79-
Tire --> Visual
80-
Lock --> Visual
81-
EV --> Visual
82-
83-
Track --> Map
84-
85-
style Visual fill:#2d3436,stroke:#fab1a0,stroke-width:2px,color:white
86-
style Header fill:#0984e3,stroke:#74b9ff,stroke-width:2px,color:white
87-
```
88-
<!-- END_MERMAID -->
35+
```yaml
8936
title: CAR
9037
badges: []
9138
cards: []

‎docs/smart-home/dashboards/dashboard-persons/daughter.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,6 @@ cards:
4343
- type: custom:decluttering-card
4444
template: family_member_notifications
4545
variables:
46-
- person: Guest 2
46+
- person: Grandpa
4747

4848
```

‎docs/smart-home/dashboards/dashboard-persons/map-all.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,10 @@ badges: []
3030
cards:
3131
- type: map
3232
entities:
33-
- entity: person.Guest 3
34-
- entity: person.Guest 2
33+
- entity: person.Guest
34+
- entity: person.Grandpa
3535
- entity: person.Evis
36-
- entity: person.Guest 1
36+
- entity: person.Grandma
3737
- entity: person.Daughter
3838
- entity: person.car
3939
hours_to_show: 2

‎docs/smart-home/dashboards/index.md‎

Lines changed: 93 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -4,53 +4,100 @@ tags:
44
- index
55
---
66

7-
# Dashboard Overview
7+
# Dashboards
88

9-
This section contains the automated documentation for all Lovelace dashboards and views.
9+
Welcome to the Home Lab Dashboards overview. The list below contains automatically generated links and summaries.
1010

11-
## Main Dashboard
12-
* [Home](main/home.md)
13-
* [Office](main/office.md)
14-
* [Bedroom](main/bedroom.md)
15-
* [Guest 2](main/guest2.md)
16-
* [Guest 3](main/guest3.md)
17-
* [Daughter](main/daughter.md)
18-
* [Living Room](main/living_room.md)
19-
* [Kitchen](main/kitchen.md)
20-
* [Hallway](main/hallway.md)
21-
* [Bathroom](main/bathroom.md)
22-
* [Sauna](main/sauna.md)
23-
* [Mud Room](main/mud_room.md)
24-
* [Toilet](main/toilet.md)
25-
* [Lobby](main/lobby.md)
26-
* [Stairs](main/stairs.md)
27-
* [Front Door](main/front-door.md)
28-
* [Backyard](main/backyard.md)
29-
* [Storage](main/storage.md)
30-
* [Settings](main/settings.md)
31-
* [Electricity](main/electricity.md)
32-
* [Electricity Dev](main/electricity-dev.md)
11+
!!! info "Auto-Generated"
12+
This list is generated automatically by scanning the contents of the `dashboards` folder.
3313

34-
## Persons
35-
* [Map All](dashboard-persons/map-all.md)
36-
* [Guest 1](dashboard-persons/guest1.md)
37-
* [Evis](dashboard-persons/evis.md)
38-
* [Guest 3](dashboard-persons/guest3.md)
39-
* [Daughter](dashboard-persons/daughter.md)
40-
* [Guest 2](dashboard-persons/guest2.md)
41-
* [Map Evis](dashboard-persons/map-evis.md)
42-
* [Map Guest 1](dashboard-persons/map-guest1.md)
43-
* [Map Guest 3](dashboard-persons/map-guest3.md)
44-
* [Map Guest 2](dashboard-persons/map-guest2.md)
45-
* [Map Daughter](dashboard-persons/map-daughter.md)
46-
* [CAR](dashboard-persons/car.md)
47-
48-
## Notification Center
49-
* [Management](notification-center/management.md)
50-
51-
## Room Management
52-
* [Settings](room-management/settings.md)
53-
54-
## Home Access
55-
* [Fingerprints](home-access/fingerprints.md)
14+
## ⚡ Active Dashboards
15+
- **[Backyard](./main/backyard.md)**
16+
<br> :material-arrow-right-bottom: *No short description provided.*
17+
- **[Bathroom](./main/bathroom.md)**
18+
<br> :material-arrow-right-bottom: *No short description provided.*
19+
- **[Bedroom](./main/bedroom.md)**
20+
<br> :material-arrow-right-bottom: *No short description provided.*
21+
- **[CAR](./dashboard-persons/car.md)**
22+
<br> :material-arrow-right-bottom: *No short description provided.*
23+
- **[Daughter](./dashboard-persons/daughter.md)**
24+
<br> :material-arrow-right-bottom: *No short description provided.*
25+
- **[Daughter](./main/daughter.md)**
26+
<br> :material-arrow-right-bottom: *No short description provided.*
27+
- **[Electricity Dev](./main/electricity-dev.md)**
28+
<br> :material-arrow-right-bottom: *No short description provided.*
29+
- **[Electricity](./main/electricity.md)**
30+
<br> :material-arrow-right-bottom: *No short description provided.*
31+
- **[Evis](./dashboard-persons/evis.md)**
32+
<br> :material-arrow-right-bottom: *No short description provided.*
33+
- **[Fingerprints](./home-access/fingerprints.md)**
34+
<br> :material-arrow-right-bottom: *No short description provided.*
35+
- **[Front Door](./main/front-door.md)**
36+
<br> :material-arrow-right-bottom: *No short description provided.*
37+
- **[Grandma](./dashboard-persons/grandma.md)**
38+
<br> :material-arrow-right-bottom: *No short description provided.*
39+
- **[Grandpa](./dashboard-persons/grandpa.md)**
40+
<br> :material-arrow-right-bottom: *No short description provided.*
41+
- **[Grandpa](./main/grandpa.md)**
42+
<br> :material-arrow-right-bottom: *No short description provided.*
43+
- **[Guest 1](./dashboard-persons/guest1.md)**
44+
<br> :material-arrow-right-bottom: *No short description provided.*
45+
- **[Guest 2](./dashboard-persons/guest2.md)**
46+
<br> :material-arrow-right-bottom: *No short description provided.*
47+
- **[Guest 2](./main/guest2.md)**
48+
<br> :material-arrow-right-bottom: *No short description provided.*
49+
- **[Guest 3](./dashboard-persons/guest3.md)**
50+
<br> :material-arrow-right-bottom: *No short description provided.*
51+
- **[Guest 3](./main/guest3.md)**
52+
<br> :material-arrow-right-bottom: *No short description provided.*
53+
- **[Guest](./dashboard-persons/guest.md)**
54+
<br> :material-arrow-right-bottom: *No short description provided.*
55+
- **[Guest](./main/guest.md)**
56+
<br> :material-arrow-right-bottom: *No short description provided.*
57+
- **[Hallway](./main/hallway.md)**
58+
<br> :material-arrow-right-bottom: *No short description provided.*
59+
- **[Home](./main/home.md)**
60+
<br> :material-arrow-right-bottom: *No short description provided.*
61+
- **[Kitchen](./main/kitchen.md)**
62+
<br> :material-arrow-right-bottom: *No short description provided.*
63+
- **[Living Room](./main/living_room.md)**
64+
<br> :material-arrow-right-bottom: *No short description provided.*
65+
- **[Lobby](./main/lobby.md)**
66+
<br> :material-arrow-right-bottom: *No short description provided.*
67+
- **[Management](./notification-center/management.md)**
68+
<br> :material-arrow-right-bottom: *No short description provided.*
69+
- **[Map All](./dashboard-persons/map-all.md)**
70+
<br> :material-arrow-right-bottom: *No short description provided.*
71+
- **[Map Daughter](./dashboard-persons/map-daughter.md)**
72+
<br> :material-arrow-right-bottom: *No short description provided.*
73+
- **[Map Evis](./dashboard-persons/map-evis.md)**
74+
<br> :material-arrow-right-bottom: *No short description provided.*
75+
- **[Map Grandma](./dashboard-persons/map-grandma.md)**
76+
<br> :material-arrow-right-bottom: *No short description provided.*
77+
- **[Map Grandpa](./dashboard-persons/map-grandpa.md)**
78+
<br> :material-arrow-right-bottom: *No short description provided.*
79+
- **[Map Guest 1](./dashboard-persons/map-guest1.md)**
80+
<br> :material-arrow-right-bottom: *No short description provided.*
81+
- **[Map Guest 2](./dashboard-persons/map-guest2.md)**
82+
<br> :material-arrow-right-bottom: *No short description provided.*
83+
- **[Map Guest 3](./dashboard-persons/map-guest3.md)**
84+
<br> :material-arrow-right-bottom: *No short description provided.*
85+
- **[Map Guest](./dashboard-persons/map-guest.md)**
86+
<br> :material-arrow-right-bottom: *No short description provided.*
87+
- **[Mud Room](./main/mud_room.md)**
88+
<br> :material-arrow-right-bottom: *No short description provided.*
89+
- **[Office](./main/office.md)**
90+
<br> :material-arrow-right-bottom: *No short description provided.*
91+
- **[Sauna](./main/sauna.md)**
92+
<br> :material-arrow-right-bottom: *No short description provided.*
93+
- **[Settings](./main/settings.md)**
94+
<br> :material-arrow-right-bottom: *No short description provided.*
95+
- **[Settings](./room-management/settings.md)**
96+
<br> :material-arrow-right-bottom: *No short description provided.*
97+
- **[Stairs](./main/stairs.md)**
98+
<br> :material-arrow-right-bottom: *No short description provided.*
99+
- **[Storage](./main/storage.md)**
100+
<br> :material-arrow-right-bottom: *No short description provided.*
101+
- **[Toilet](./main/toilet.md)**
102+
<br> :material-arrow-right-bottom: *No short description provided.*
56103

‎docs/smart-home/dashboards/main/bedroom.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ sections:
6767
indicator_3_entity: input_boolean.bed_Evis_occupancy
6868
indicator_3_icon: mdi:bed
6969
indicator_3_state: 'on'
70-
indicator_4_entity: input_boolean.bed_Guest 1_occupancy
70+
indicator_4_entity: input_boolean.bed_Grandma_occupancy
7171
indicator_4_icon: mdi:bed
7272
indicator_4_state: 'on'
7373
indicator_4_active_color: '#FF44C4'
@@ -249,7 +249,7 @@ sections:
249249
double_tap_action:
250250
action: none
251251
- type: custom:mushroom-template-card
252-
primary: "Guest 1 {% set status = states(entity) %}\n{% if status == 'on'\
252+
primary: "Grandma {% set status = states(entity) %}\n{% if status == 'on'\
253253
\ %}\n in Bed\n{% else %}\n not in Bed\n{% endif %}"
254254
secondary: ''
255255
icon: "{% set status = states(entity) %}\n{% if status == 'on' %}\n mdi:bed\n\
@@ -290,11 +290,11 @@ sections:
290290
name: Pressure
291291
icon: mdi:bed-outline
292292
state_color: true
293-
- entity: binary_sensor.bedroom_bed_Guest 1_fp2_occupancy
293+
- entity: binary_sensor.bedroom_bed_Grandma_fp2_occupancy
294294
name: Bed FP2
295295
icon: mdi:bed
296296
state_color: true
297-
- entity: binary_sensor.bedroom_bedside_Guest 1_fp2_sensor
297+
- entity: binary_sensor.bedroom_bedside_Grandma_fp2_sensor
298298
name: Bedside
299299
icon: mdi:walk
300300
state_color: true

0 commit comments

Comments
 (0)