feat: initialise cluster superproject with submodules and platform docs

2026-10-18 14:22:34 +02:00
commit a362b05637
14 changed files with 734 additions and 0 deletions
@@ -0,0 +1,65 @@
+# AI Agent & Developer Cheatsheet
+
+Dit document bevat richtlijnen, veelvoorkomende commando's en belangrijke valkuilen voor het werken in deze workspace.
+
+---
+
+## ⚠️ Belangrijke Valkuilen & Regels
+
+1. **Root is de Git meta-repository (met Git submodules)**:
+   * `/home/bart/git/cluster` beheert het superproject, submodules en de overkoepelende documentatie in `docs/`.
+   * Gebruik `git submodule update --init --recursive` om submodules binnen te halen of bij te werken.
+   * Commits op codebase-niveau voer je uit binnen de desbetreffende submodule map (bijv. `git -C cluster-infra ...` of navigeer naar de map).
+   * Werk vervolgens desgewenst de submodule pointers bij in de root repository.
+2. **Submodule status & wijzigingen**:
+   * Let op 'dirty' of untracked files binnen submodules (`git status` in de root toont of een submodule gewijzigd is).
+3. **CI/CD Triggers via Path Filtering**:
+   * Zowel `cluster-infra` als `HERMS` gebruiken `dorny/paths-filter`. Wijzigingen in documentatie of mappen die niet in de filters staan triggeren geen container build.
+   * Controleer bij het toevoegen van nieuwe componenten of de workflow (`.gitea/workflows/*.yaml`) het pad herkent.
+4. **GitOps Manifest Synchronisatie**:
+   * Pas productie Kubernetes manifests bij voorkeur aan in de bronrepository (bijv. in `cluster-infra/<service>/k8s` of `HERMS/deployments`), zodat de CI/CD pipeline ze gesynchroniseerd kan overzetten naar `k8s-infra-vmserver`.
+   * Direct wijzigen in `k8s-infra-vmserver` kan leiden tot overschrijvingen bij een volgende geautomatiseerde build als dezelfde bestanden vanuit de bron worden gepusht.
+
+---
+
+## 🛠️ Snelle Commando's
+
+### Git Status over alle repositories
+```bash
+for d in cluster-infra HERMS k8s-infra-vmserver smart-home; do
+  echo "=== $d ==="
+  git -C "$d" status -s
+done
+```
+
+### Git Remotes verifiëren
+```bash
+for d in cluster-infra HERMS k8s-infra-vmserver smart-home; do
+  echo "=== $d ==="
+  git -C "$d" remote -v
+done
+```
+
+### Recente commits bekijken
+```bash
+for d in cluster-infra HERMS k8s-infra-vmserver smart-home; do
+  echo "=== $d ==="
+  git -C "$d" log -n 1 --oneline
+done
+```
+
+---
+
+## 🎨 Design & Coding Conventies
+
+* **Frontend (`HERMS/frontend`)**:
+  * **Thema**: SevenGrid Aurora Dark (`#0A0F12` background, Teal `#1DC7B7` accent, Coral `#E26F3A` verwarmingsaccent).
+  * **Styling**: Tailwind CSS met `rounded-full` pills voor status en switches.
+  * **Communicatie**: REST via storage API + WebSocket stream voor live telemetry.
+* **Backend Services (`HERMS`)**:
+  * Geschreven in **Rust** (Cargo workspace of individuele crates).
+  * Foutafhandeling met duidelijke loguitvoer (`tracing` / `log`).
+* **MQTT Topics**:
+  * Altijd strings voor heaters (`hlt`, `mlt`, `boil`).
+  * Telemetrie publiceren met `retain: true`.
+  * Commando's op `/cmd`, bevestiging op `/state`.