Skip to content

Commit 2fc4556

Browse files
webosawebosa
committed
Update System Manual to 5.1
1 parent 669ef38 commit 2fc4556

3 files changed

Lines changed: 412 additions & 13 deletions

File tree

‎AI_CONTEXT.md.1765111534.bak‎

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/system_manual/setup_guide.md‎

Lines changed: 24 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# EvisHomeLab: Documentation System Manual
22

3-
**Version:** 5.0
3+
**Version:** 5.1
44
**Philosophy:** Agentic CMDB (Configuration Management Database)
55
**Strategy:** "Detached Docs" (Private Config -> Public Documentation)
66

@@ -86,12 +86,13 @@ CRITICAL RULES:
8686

8787
We rely on Python scripts to manage complex tasks.
8888

89-
**A. Create `ag_update_docs.py`**
90-
* **Purpose:** The Master Installer. Updates this manual, the AI Context, and the dashboard tools.
91-
* **How:** Copy the content from the repository history or backup.
89+
**A. `ag_update_docs.py` (The Architect's Tool)**
90+
* **Purpose:** The Source of Truth. Updates this manual, the AI Context, and scripts.
91+
* **Usage:** Run `python ag_update_docs.py` whenever you update the system design.
9292

93-
**B. Run it:**
94-
* Run `python ag_update_docs.py` to auto-generate `ag_regenerate_dashboards.py`.
93+
**B. `ag_regenerate_dashboards.py` (The Formatter)**
94+
* **Purpose:** Converts JSON dashboards to YAML.
95+
* **Usage:** Run `python ag_regenerate_dashboards.py` to refresh dashboard docs.
9596

9697
### 4. Scaffold Documentation Site
9798

@@ -213,14 +214,19 @@ We use YAML frontmatter to categorize pages. This enables Tag Clouds on the webs
213214
## PART D: Daily Operations (The Workflow)
214215

215216
### 1. The Full Maintenance Cycle (Recommended Routine)
216-
1. **Update Tools:** Run `python ag_update_docs.py` (Ensures you have the latest manual and scripts).
217-
2. **Regenerate Dashboards:** Run `python ag_regenerate_dashboards.py` (Scans HA, redacts names, writes Markdown).
217+
Run these commands in order to keep everything synced. The `cd /` commands ensure you are in the project root before execution.
218+
219+
1. **Update Tools:**
220+
```powershell
221+
cd /; python ag_update_docs.py
222+
```
223+
2. **Regenerate Dashboards:**
224+
```powershell
225+
cd /; python ag_regenerate_dashboards.py
226+
```
218227
3. **Publish:**
219-
```bash
220-
cd docs_site
221-
git add .
222-
git commit -m "Routine update"
223-
git push
228+
```powershell
229+
cd docs_site; git add .; git commit -m "Routine update"; git push
224230
```
225231
226232
### 2. The AI Architect Workflow (Resume Work)
@@ -263,6 +269,11 @@ Paste this prompt to "hydrate" the AI with the project context:
263269
> 1. Re-scan the root directory and update the file tree structure description (Folders first, then files).
264270
> 2. Read `configuration.yaml` and update the commented code block explanation."
265271
272+
**Task: Enable Tags & Tag Cloud**
273+
> "Edit `docs_site/mkdocs.yml`.
274+
> 1. Under `plugins:`, add `- tags`.
275+
> 2. Commit changes: 'Enable MkDocs Tags plugin'."
276+
266277
**Task: Convert Dashboard to YAML**
267278
> "Run `python ag_regenerate_dashboards.py`."
268279

0 commit comments

Comments
 (0)