cluster/docs/agent-cheatsheet.md

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

for d in cluster-infra HERMS k8s-infra-vmserver smart-home; do
  echo "=== $d ==="
  git -C "$d" status -s
done

Git Remotes verifiëren

for d in cluster-infra HERMS k8s-infra-vmserver smart-home; do
  echo "=== $d ==="
  git -C "$d" remote -v
done

Recente commits bekijken

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.