# 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`.