Skip to content

Commit f8c3bc0

Browse files
webosawebosa
committed
Re-initialize documentation repository
0 parents  commit f8c3bc0

30 files changed

Lines changed: 1859 additions & 0 deletions

‎.github/workflows/deploy_docs.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: Deploy Docs
2+
on:
3+
push:
4+
branches:
5+
- main
6+
permissions:
7+
contents: write
8+
jobs:
9+
deploy:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: actions/setup-python@v5
14+
with:
15+
python-version: 3.x
16+
- run: pip install mkdocs-material
17+
- run: mkdocs gh-deploy --force --config-file mkdocs.yml

‎AI_CONTEXT.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
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):** You must replace ALL occurrences of family names, **including lowercase variants** found in code variables or entity IDs.
23+
24+
* 'Jukka' OR 'jukka' -> 'Evis'
25+
* 'Alisa' OR 'alisa' -> 'Daughter'
26+
* 'Piia' OR 'piia' -> 'Grandma'
27+
* 'Elias' OR 'elias' -> 'Grandpa'
28+
* 'Anton' OR 'anton' -> 'Guest'
29+
30+
## 3. Documentation Style Guide
31+
32+
* **Structure:** Follow the CMDB hierarchy (`docs/smart-home/packages/`, `docs/smart-home/dashboards.md`).
33+
34+
* **Metadata (Tags):**
35+
* All Markdown files should start with YAML Frontmatter.
36+
* **Locking:** If a file contains `auto_update: false`, **DO NOT EDIT IT**.
37+
* **Tags:** Use `tags: [category, status]` (e.g., `tags: [package, manual]`).
38+
39+
* **Visuals (Web Designer Role):**
40+
* **Mermaid JS:** Use sequence diagrams for logic flow.
41+
* **No Fakes:** Do NOT generate fake HTML/CSS UI simulations.
42+
* **Screenshots:** Use the "Drop & Link" method.
43+
* Dashboard Views -> `assets/images/dashboards/`
44+
* Package Cards -> `assets/images/packages/`
45+
* **Styling:** Use Admonitions (`!!! info`) for architectural notes.
46+
47+
* **Format:**
48+
* **YAML Conversion:** When converting JSON (dashboards) to YAML, ensure **multi-line formatting** with 2-space indentation. NEVER output single-line object dumps.
49+
* Use Standard YAML code blocks for configuration.
50+
51+
## 4. Coding Standards for Scripts
52+
53+
When creating Python or Shell scripts for this project:
54+
55+
1. **Naming Convention:** All helper tools must start with `ag_` (e.g., `ag_regenerate_dashboards.py`).
56+
2. **File Headers:** Every script must begin with a standard comment block:
57+
```python
58+
# -----------------------------------------------------------------------------
59+
# File: [filename]
60+
# Version: [version]
61+
# Description: [short summary]
62+
# Usage: [command to run]
63+
# -----------------------------------------------------------------------------
64+
```
65+
66+
## 5. Deployment Logic
67+
68+
* The site is built via **GitHub Actions**.
69+
* We must push changes from the `docs_site/` directory to trigger a build.
70+
* **CNAME:** Ensure `docs/CNAME` exists and contains `www.evishome.com`.
71+
72+
## 6. Project History & Architectural Decisions (ADRs)
73+
74+
*This section captures 'Silent Knowledge' and lessons learned.*
75+
76+
1. **ADR-001: Detached Documentation:**
77+
* **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.
78+
79+
2. **ADR-002: Dashboard Generation via Python:**
80+
* **Failure:** Using LLMs to "rewrite" JSON dashboards often results in broken YAML or single-line dumps.
81+
* **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.
82+
83+
3. **ADR-003: Samba & Git Ownership:**
84+
* **Issue:** Windows clients accessing HA via Samba see "Dubious Ownership" errors because the files are owned by `root` on the server.
85+
* **Fix:** We enforce `git config --global --add safe.directory '*'` on all dev machines.
86+
87+
4. **ADR-004: MkDocs Material Features:**
88+
* **Decision:** We explicitly enable `navigation.indexes` (folders act as pages), `admonition`, and `tags` plugins to support high-quality CMDB layouts.

‎docs/CNAME‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
www.evishome.com

‎docs/assets/css/custom.css‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
/* Make H1, H2, and H3 headers Orange (using the Accent color variable) */
2+
.md-typeset h1,
3+
.md-typeset h2,
4+
.md-typeset h3 {
5+
color: var(--md-accent-fg-color);
6+
font-weight: bold;
7+
}
8+
9+
/* Add separator line before System Manual in Sidebar */
10+
/* Make H1, H2, and H3 headers Orange (using the Accent color variable) */
11+
.md-typeset h1,
12+
.md-typeset h2,
13+
.md-typeset h3 {
14+
color: var(--md-accent-fg-color);
15+
font-weight: bold;
16+
}
17+
18+
/* Add separator line before System Manual in Sidebar */
19+
.md-nav__item a[href*='system_manual'] {
20+
margin-top: 15px;
21+
padding-top: 15px;
22+
border-top: 1px solid var(--md-default-fg-color--lightest);
23+
}
24+
25+
/* Add separator line below Home in Sidebar */
26+
.md-nav__item a[href^='index.md'],
27+
.md-nav__item a[href='.'] {
28+
margin-bottom: 15px;
29+
padding-bottom: 15px;
30+
border-bottom: 1px solid var(--md-default-fg-color--lightest);
31+
}

‎docs/assets/images/.gitkeep‎

Whitespace-only changes.

‎docs/home-lab/index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Home Lab
2+
3+
*Placeholder for Server & VM documentation.*
4+
5+
## Infrastructure
6+
- **Servers**: (To be documented)
7+
- **Virtual Machines**: (To be documented)
8+
- **Containers**: (To be documented)

‎docs/index.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# EvisHomeLab
2+
3+
Welcome to the EvisHomeLab documentation.
4+
5+
## Sections
6+
- **[Smart Home Documentation](smart-home/index.md)**: Home Assistant configuration, automations, and dashboards.
7+
- **[Home Lab](home-lab/index.md)**: Server infrastructure, VMs, and containers.
8+
- **[Network](network/index.md)**: Network topology, VLANs, and firewall rules.
9+
10+
!!! info "System Architecture & Maintenance"
11+
This documentation site is managed via an **Agentic CMDB Workflow**. It is automatically generated from the live Home Assistant configuration using Google Antigravity.
12+
13+
* **Strategy:** Detached Docs (Private Config → Public Site)
14+
* **Tools:** Home Assistant OS, Antigravity IDE, Git, MkDocs Material
15+
16+
[📖 **Read the full System Setup & Maintenance Manual**](system_manual/setup_guide.md)

‎docs/network/index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Network Topology
2+
3+
*Placeholder for Network documentation.*
4+
5+
## Overview
6+
- **Router**: (To be documented)
7+
- **Switches**: (To be documented)
8+
- **VLANs**: (To be documented)

‎docs/smart-home/automations.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Automations & Packages
2+
3+
This page documents the automation packages found in the `packages/` directory.
4+
5+
| File | Purpose | Triggers | Key Entities |
6+
| :--- | :--- | :--- | :--- |
7+
| `airthings.yaml` | Air quality sensors template | *(Template)* | `sensor.airthings_wave_*` |
8+
| `aqara_w500.yaml` | HVAC/Temp sensors & filters | *(Template)* | `sensor.aqara_w500_*` |
9+
| `car_glc.yaml` | Car status normalization | *(Template)* | `binary_sensor.car_glc_*` |
10+
| `dishwasher.yaml` | Dishwasher status & timer logic | *(Template)* | `binary_sensor.dishwasher_*`, `input_boolean.dishwasher_*` |
11+
| `dna_tv_hub.yaml` | TV Hub remote switch | *(Template)* | `switch.dna_tv_hub` |
12+
| `fingerprint_management.yaml` | Dynamic Fingerprint MQTT Management | MQTT (`.../user/set`) | `script.add_fingerprint_entity`, `automation.system_fingerprint_mqtt_persistence` |
13+
| `garmin.yaml` | *(Empty)* | - | - |
14+
| `home_time_modes.yaml` | Time-of-Day Logic (Day/Night/Evening) | Time, Sun, Time Pattern | `input_select.house_mode`, `automation.system_manager_home_time_modes` |
15+
| `mercedes_glc.yaml` | Car control & sensors | *(Template)* | `switch.car_*`, `binary_sensor.car_*` |
16+
| `nordpool_prices.yaml` | Electricity prices & 15min cost calculation | Time Pattern, HA Start, State | `sensor.electricity_prices`, `nordpool.get_prices_for_date` |
17+
| `office._pc.yaml` | Office PC Control (WOL, Audio, Display) | *(Template/WOL)* | `switch.office_pc_*` |
18+
| `philips_air_purifier.yaml` | Air Purifier sensors | *(Template)* | `sensor.purifier_*` |
19+
| `room_automation.yaml` | Dynamic Room Settings via MQTT | MQTT (`room/#`), HA Start, Time Pattern | `script.create_room_settings`, `automation.system_populate_room_list` |
20+
| `scenes.yaml` | Lighting Scene Definitions | - | `scene.daylight_scene`, `scene.bedroom_mood`, etc. |
21+
| `shelly_3em.yaml` | Total Power Aggregation | *(Template)* | `sensor.home_total_power`, `sensor.home_energy_15min` |
22+
| `smart_notifications.yaml` | Dynamic Notification Router & User Mgmt | HA Start, Time Pattern, MQTT (`notify/#`) | `script.notify_smart_master`, `automation.system_populate_notify_services` |

‎docs/smart-home/dashboards.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
tags:
3+
- dashboard
4+
- automated
5+
---
6+
7+
# Home Assistant Dashboards
8+
9+
This documentation is automatically generated from the live configuration.
10+
11+
## Dashboard: XDEV
12+
13+
**URL:** `/dashboard-dev`
14+
15+
> *No views found or configuration is stored separately.*
16+
17+
## Dashboard: Persons
18+
19+
**URL:** `/dashboard-persons`
20+
21+
> *No views found or configuration is stored separately.*
22+
23+
## Dashboard: System
24+
25+
**URL:** `/dashboard-system`
26+
27+
> *No views found or configuration is stored separately.*
28+
29+
## Dashboard: Remotes
30+
31+
**URL:** `/dashboard-popups`
32+
33+
> *No views found or configuration is stored separately.*
34+
35+
## Dashboard: Room-PopUps
36+
37+
**URL:** `/room-popups`
38+
39+
> *No views found or configuration is stored separately.*
40+
41+
## Dashboard: Demo
42+
43+
**URL:** `/dashboard-demo`
44+
45+
> *No views found or configuration is stored separately.*
46+
47+
## Dashboard: Map
48+
49+
**URL:** `/map`
50+
51+
> *No views found or configuration is stored separately.*
52+
53+
## Dashboard: DEV
54+
55+
**URL:** `/dashboard-dev2`
56+
57+
> *No views found or configuration is stored separately.*
58+
59+
## Dashboard: Notification Center
60+
61+
**URL:** `/notification-center`
62+
63+
> *No views found or configuration is stored separately.*
64+
65+
## Dashboard: Room Management
66+
67+
**URL:** `/room-management`
68+
69+
> *No views found or configuration is stored separately.*
70+
71+
## Dashboard: Home Access
72+
73+
**URL:** `/home-access`
74+
75+
> *No views found or configuration is stored separately.*
76+
77+
## Dashboard: Zigbee2MQTT
78+
79+
**URL:** `/dashboard-zigbee2mqtt`
80+
81+
> *No views found or configuration is stored separately.*
82+

0 commit comments

Comments
 (0)