claude_settings/CLAUDE.md

Global Claude Code Instructions

🚨 PFLICHT-CHECKLISTE BEI TASK-ABSCHLUSS 🚨

DIESE CHECKLISTE IST NICHT OPTIONAL. SIE MUSS BEI JEDER ABGESCHLOSSENEN AUFGABE DURCHGEFÜHRT WERDEN.

BEVOR du dem User sagst, dass du fertig bist, gehe diese Liste durch:

Bei JEDER Dokumentationsarbeit (README, Config-Docs, etc.):

• Verifikation durchgeführt?

  • Vergleichstabelle: Quelle ↔ Dokumentation erstellt
  • ALLE Abschnitte geprüft (nicht nur die offensichtlichen)
  • Finale Checkliste mit Zeilennummern erstellt
  • Bestätigung: "X/X Abschnitte vollständig dokumentiert"

• Infrastructure-Repo aktualisiert?

  • Wenn Kunde erkannt (~/Nextcloud/[kunde]/):
    • infrastructure/hosts/[host].md aktualisiert?
      • Für JEDEN Host auf dem gearbeitet wurde (auch indirekt, z.B. Reverse Proxy, DNS-Server)
    • infrastructure/dependencies.md aktualisiert?
      • Mermaid-Diagramme: Neue Verbindungen/Abhängigkeiten eingezeichnet?
      • Referenz-Tabellen: Neue Hosts ergänzt?
      • Impact-Analyse: Neue Ausfallszenarien?
    • infrastructure/netzwerk/domains.md aktualisiert?
      • Neue Subdomains eingetragen?
      • DNS-Änderungen reflektiert?
  • Änderungen committet und gepusht?

Bei JEDEM Task-Abschluss:

• Alle Änderungen committet und gepusht?

  • Aktuelles Repo
  • Infrastructure-Repo (falls relevant)

• Settings-Sync geprüft?

  cd ~/dotfiles/claude_settings && git fetch origin && git status
  

• Kontinuierliche Verbesserung: Erkenntnisse für globale Anweisungen?

  • Prüfe: Gab es in dieser Session Erkenntnisse, Patterns oder Pitfalls, die auch in zukünftigen Sessions (projektübergreifend) nützlich wären?
  • Kandidaten sind:
    • Neue Workflow-Patterns (z.B. "immer erst X prüfen bevor Y")
    • API-/Tool-Eigenheiten die wiederholt auftreten
    • Fehler die durch bessere Anweisungen vermeidbar wären
    • Neue Host-Typen oder Zugangs-Patterns (z.B. "pfSense → immer root")
    • Dokumentations-Strukturen die sich bewährt haben
  • Falls ja: Dem User vorschlagen, welche Punkte in CLAUDE.md aufgenommen werden sollten
  • Falls nein: Kurz bestätigen: "Keine neuen globalen Erkenntnisse aus dieser Session"
  • Wichtig: Nicht selbst entscheiden — dem User die Erkenntnisse vorlegen und ihn entscheiden lassen

⚠️ WICHTIG

Du darfst NICHT:

• Sagen "Erledigt" ohne diese Checkliste durchzugehen
• Den User fragen ob er die Checkliste will - sie ist PFLICHT
• Schritte überspringen weil sie "offensichtlich nicht nötig" sind
• Warten bis der User dich an fehlende Schritte erinnert

Der User verlässt sich darauf, dass du diese Anweisungen IMMER befolgst.

---

⚠ MANDATORY: Settings-Synchronisierung

Repository: git@gitea.egonetix.de:root/claude_settings.git (Port 222) Lokaler Pfad: ~/dotfiles/claude_settings

Bei jedem Session-Start prüfen

cd ~/dotfiles/claude_settings && git fetch origin && git status

Falls Änderungen vorhanden:

git pull origin main

Nach Änderungen an Settings pushen

Wenn du Änderungen an folgenden Dateien vornimmst, MUSST du diese committen und pushen:

• settings.json - Globale Einstellungen
• CLAUDE.md - Diese Instruktionen
• agents/*.md - Benutzerdefinierte Agenten
• rules/*.md - Modulare Regeln
• statusline-command.sh - Statuszeilen-Script

cd ~/dotfiles/claude_settings
git add -A
git commit -m "Beschreibung der Änderung"
git push origin main

---

Copilot Instructions Skill

Maintain living documentation for every coding project via copilot-instructions.md in the project root.

---

Mandatory Workflow

Step 1: Determine Project Type

Check for existing project indicators:

• Git repository (.git/ directory)
• copilot-instructions.md file
• PROJECT_OVERVIEW.md file

If ANY exist → Ongoing Project: Follow full documentation workflow.

If NONE exist → Ask the user:

"This looks like a new workspace. Should I treat this as a one-time task, or set it up as an ongoing project with documentation and git?"

If user wants an ongoing project:

1. Initialize git repo if missing (git init)
2. Create copilot-instructions.md with initial structure
3. Optionally create PROJECT_OVERVIEW.md for complex systems

Step 2: For Ongoing Projects

1. Read existing copilot-instructions.md and PROJECT_OVERVIEW.md to understand the system
2. Scan the codebase/system to gather context and minimize follow-up questions
3. Update documentation if the current work affects architecture, patterns, entities, or conventions
4. Commit all changes to git immediately after completion

---

Document Structure

copilot-instructions.md (Development Guidelines)

Procedural knowledge for working on the project — patterns, conventions, pitfalls, workflows.

# Project Name - Copilot Instructions

## ⚠ MANDATORY RULES - NON-NEGOTIABLE
[Project-specific rules, commit conventions, critical warnings]

## Architecture Overview
[High-level system description, key integrations, tech stack]

## File Structure
[Directory tree with annotations]

## [Domain-Specific Sections]
[Devices, APIs, services, databases - whatever is relevant]
- Working code examples with explanations
- Configuration snippets that actually work
- Debug commands

## Patterns & Conventions
[Reusable patterns, naming conventions, code examples]

## Development Workflow
[How to test, deploy, access systems]

## Pitfalls to Avoid
[Gotchas, inverted logic, non-obvious behaviors, troubleshooting]

PROJECT_OVERVIEW.md (System Reference)

Factual inventory of what exists — devices, integrations, entities, IPs. Use for complex systems with many components.

# Project Overview

## System Information
[Version, host, IP, access details]

## Network Architecture
[Diagram or list of hosts/devices]

## Installed Components
[Add-ons, plugins, integrations with purpose]

## Entity/Device Inventory
[Tables of devices, entity IDs, purposes]

## Quick Reference
[Common commands, URLs, access methods]

When to create PROJECT_OVERVIEW.md:

• Systems with many devices/entities (IoT, home automation)
• Infrastructure projects with multiple hosts
• Projects where entity/device inventory changes frequently

---

Content Guidelines

Include:

• Working code/config snippets (tested and verified)
• Actual entity names, IPs, paths (not placeholders)
• Debug commands and troubleshooting tables
• Lessons learned from debugging sessions
• Non-obvious behavior ("contact sensor: on=OPEN, off=CLOSED")
• Git commit references for significant changes

Exclude:

• Secrets, tokens, passwords (reference secrets.yaml or .env instead)
• Obvious boilerplate explanations
• Duplicate information

Language: Match the user's language. Mixed language is acceptable when technical terms are clearer in English.

---

Git Commit Convention

After every change:

cd /path/to/project
git add -A
git commit -m "Descriptive message in user's language"
git push origin main  # or appropriate branch

Commit messages should describe what changed, not just "updated docs".

---

Referencing Git Commits

For significant development work, reference the relevant commit(s) in the documentation:

## Tasmota SML Integration

**Implemented:** 2025-01-21 | Commits: `a3f2b1c`, `e7d4a9f`

[Documentation of the feature...]

When to add commit references:

• New features or integrations
• Major refactors
• Complex bug fixes that required multiple attempts
• Configuration changes that took significant debugging

Format options:

• Single commit: Commit: a3f2b1c
• Multiple commits: Commits: a3f2b1c, e7d4a9f, b2c3d4e
• Commit range: Commits: a3f2b1c..e7d4a9f

Get the short hash after committing:

git log -1 --format="%h"  # Most recent commit
git log -3 --format="%h %s"  # Last 3 with messages

---

When to Update copilot-instructions.md

Update when:

• Adding new integrations, devices, or services
• Discovering non-obvious behavior or gotchas
• Establishing new patterns or conventions
• Fixing bugs that reveal important system behavior
• Changing architecture or file structure

Don't update for:

• Minor code changes that don't affect understanding
• Temporary debugging that will be removed

---

New Project Onboarding

When a user requests to set up a new ongoing project:

1. Connect and explore the system to understand what exists
2. Scan broadly — gather device lists, integrations, file structures, configurations
3. Create documentation based on findings:
   • copilot-instructions.md for development guidelines and patterns
   • PROJECT_OVERVIEW.md for system inventory (if complex)
4. Initialize git if not present
5. Commit initial documentation

This upfront investment minimizes questions in future sessions and enables faster, more informed development.

---

Infrastruktur-Dokumentationssystem

Ziel und Vision

Die detaillierte Infrastruktur-Dokumentation dient einem größeren Ziel:

Phase 1: Dokumentation (aktuell)

• Vollständige Erfassung aller Hosts, Dienste, Abhängigkeiten
• Maschinenlesbare Struktur (Markdown mit konsistenten Tabellen)
• Abhängigkeitsgraphen in Mermaid

Phase 2: Zabbix-Integration

• Abhängigkeiten aus dependencies.md → Zabbix Host Dependencies
• Wiederkehrende Probleme → Zabbix Trigger + Actions
• Host-Dokumentation → Zabbix Host Inventory
• Impact-Analysen → Zabbix Service Monitoring

Phase 3: Self-Healing durch KI

• KI analysiert Zabbix-Alerts + Dokumentation
• Automatische Diagnose basierend auf dokumentierten Abhängigkeiten
• Automatische Remediation für bekannte Probleme
• Lernschleife: Neue Probleme → Dokumentation → Zabbix → KI

Konsequenzen für die Dokumentation:

• Vollständigkeit ist kritisch - fehlende Abhängigkeiten = blinde Flecken für KI
• Konsistente Struktur - ermöglicht maschinelles Parsing
• Wiederkehrende Probleme dokumentieren - werden zu automatisierbaren Fixes
• Impact bei Ausfall - definiert Prioritäten für automatische Reaktionen

Organisation pro Kunde

Gitea-Struktur:

├── Vinos/                       ← Organisation für Kunde "vinos"
│   ├── infrastructure.git       ← Landkarte für vinos
│   ├── zabbix.git               ← System-Repo
│   └── [weitere].git            ← Dienst-/System-Repos
│
└── Egonetix/                    ← Organisation für Kunde "egonetix"
    ├── infrastructure.git       ← Landkarte für egonetix
    └── [weitere].git

Lokale Struktur:

~/Nextcloud/
├── vinos/                       ← Kunde vinos
│   ├── infrastructure/          ← Landkarte (dependencies.md, hosts/)
│   ├── zabbix/                  ← System-Repo
│   └── [weitere]/               ← Dienst-/System-Repos
│
└── egonetix/                    ← Kunde egonetix
    ├── infrastructure/
    └── [weitere]/

Repo-Typen

Repo-Typ	Gitea-Ort	Inhalt
Infrastructure	[Kunde]/infrastructure.git	Landkarte, Abhängigkeiten, Host-Übersichten
System-Repo	[Kunde]/[system].git	README, Konfig-Dateien, Troubleshooting
Dienst-Repo	[Kunde]/[dienst].git	docker-compose.yml, Code, Workflows

Automatische Erkennung (Hook-gesteuert)

Der Session-Start Hook erkennt Kunden-Verzeichnisse unter ~/Nextcloud/[kunde]/.

Wenn du <REPO_SETUP_REQUIRED> in der Hook-Ausgabe siehst:

1. Frage den User:

   "Ich habe erkannt, dass für dieses Repo noch Setup erforderlich ist. Soll ich das automatisch durchführen?"

2. Bei Zustimmung - führe alle fehlenden Schritte aus:

   # Git initialisieren (falls nicht vorhanden)
   git init
   git branch -M main
   
   # Template aus infrastructure/_templates/ kopieren
   

3. Repo auf Gitea erstellen (API):

   curl -X POST -H "Authorization: token $GITEA_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"repo-name","description":"..."}' \
     https://gitea.egonetix.de/api/v1/orgs/[Kunde]/repos
   

4. Remote hinzufügen und pushen:

   git remote add origin ssh://git@gitea.egonetix.de:222/[Kunde]/[repo-name].git
   git push -u origin main
   

Gitea Remote-Konfiguration

URL-Format:

ssh://git@gitea.egonetix.de:222/[Kunde]/[repo-name].git

Beispiele:

Kunde	Repo	Remote URL
Vinos	infrastructure	ssh://git@gitea.egonetix.de:222/Vinos/infrastructure.git
Vinos	zabbix	ssh://git@gitea.egonetix.de:222/Vinos/zabbix.git
Egonetix	infrastructure	ssh://git@gitea.egonetix.de:222/Egonetix/infrastructure.git

Gitea Tooling

Token-Speicherort (NICHT im Git-Sync!):

~/.config/gitea/token

Verfügbare Tools:

Tool	Befehl	Anwendung
tea CLI	~/bin/tea	Vollständige Gitea-Interaktion
curl + API	curl -H "Authorization: token $(cat ~/.config/gitea/token)"	Einfache API-Aufrufe

tea CLI Beispiele:

# Repos auflisten
~/bin/tea repos list

# Neues persönliches Repo erstellen
~/bin/tea repos create --name mein-repo --description "Beschreibung"

# Neues Repo in Organisation erstellen
~/bin/tea repos create --owner Vinos --name repo-name

# Issues auflisten
~/bin/tea issues list

# PR erstellen
~/bin/tea pr create --title "Feature X" --description "..."

curl API Beispiele:

# Persönliches Repo erstellen
curl -X POST -H "Authorization: token $(cat ~/.config/gitea/token)" \
  -H "Content-Type: application/json" \
  -d '{"name":"repo-name","description":"...","private":false}' \
  https://gitea.egonetix.de/api/v1/user/repos

# Repo in Organisation erstellen
curl -X POST -H "Authorization: token $(cat ~/.config/gitea/token)" \
  -H "Content-Type: application/json" \
  -d '{"name":"repo-name","description":"..."}' \
  https://gitea.egonetix.de/api/v1/orgs/[Org]/repos

Wichtig: Der Token wird LOKAL gespeichert und NICHT nach ~/dotfiles/claude_settings synchronisiert.

Workflow: Neues System-/Dienst-Repo anlegen

cd ~/Nextcloud/[kunde]
git init [repo-name]
cd [repo-name]
# Template aus ../infrastructure/_templates/ kopieren
# Repo auf Gitea erstellen
# git remote add origin ...
# git push -u origin main

Dokumentations-Verifikation (PFLICHT)

Bei jeder Dokumentationsarbeit MUSS eine zweistufige Verifikation durchgeführt werden:

• Neue Dokumentation erstellen
• Bestehende Dokumentation umstrukturieren
• Inhalte aus anderen Quellen übernehmen
• Dokumentation aufteilen oder zusammenführen

Schritt 1: Erstvergleich

Nach Abschluss der Dokumentationsarbeit, erstelle eine Vergleichstabelle:

| Abschnitt (Original) | Neue Datei | Status |
|---------------------|------------|--------|
| [Abschnitt 1] | [datei.md:zeilen] | ✅/❌ |
| [Abschnitt 2] | [datei.md:zeilen] | ✅/❌ |
...

• Liste JEDEN Abschnitt der Quelldokumentation auf
• Prüfe ob er in der neuen Struktur vorhanden ist
• Markiere fehlende Abschnitte mit ❌

Schritt 2: Fehlende Inhalte ergänzen

• Ergänze alle mit ❌ markierten Abschnitte
• Committe die Änderungen

Schritt 3: Erneute Verifikation (PFLICHT)

Nach dem Ergänzen MUSS eine erneute, vollständige Prüfung erfolgen:

1. Lies alle neuen Dateien nochmals
2. Erstelle eine finale Checkliste mit Zeilennummern:

| # | Abschnitt | Datei:Zeilen | Status |
|---|-----------|--------------|--------|
| 1 | [Name] | README.md:15-18 | ✅ |
| 2 | [Name] | hosts.md:5-8 | ✅ |
...

3. Bestätige: "X/X Abschnitte vollständig dokumentiert. Keine Inhalte wurden vergessen."

Schritt 4: Zweiter unabhängiger Review-Pass (PFLICHT)

Nach Schritt 3 MUSS ein zweiter, komplett unabhängiger Review-Pass erfolgen. Dieser Schritt existiert, weil erfahrungsgemäß beim ersten Durchgang Fehler übersehen werden, die erst bei einer Nachfrage auffallen. Der User soll NICHT nachfragen müssen.

Vorgehen:

1. Alle bearbeiteten Dateien nochmals KOMPLETT lesen (nicht überfliegen)
2. Gezielt prüfen — andere Perspektive als Schritt 3:
   • Links: Sind alle Markdown-Links gültig? Anker korrekt (keine Leerzeichen, Sonderzeichen)?
   • Diagramme: Spiegeln Mermaid-Diagramme den aktuellen Stand wider? Neue Knoten/Kanten nötig?
   • Querverweise: Stimmen Referenz-Tabellen nach Diagrammen mit den tatsächlichen Knoten überein?
   • Abhängigkeiten: Sind alle neuen Abhängigkeiten in dependencies.md eingetragen (Mermaid + Impact-Tabelle)?
   • Konsistenz: Stimmen Angaben (IPs, Ports, Hostnamen, Netze) zwischen README und dependencies.md überein?
   • Vollständigkeit: Gibt es Erkenntnisse aus der Session, die NICHT dokumentiert sind? (Pitfalls, Workarounds, TODOs)
3. Gefundene Fehler sofort fixen und committen
4. Bestätige: "Zweiter Review-Pass abgeschlossen. X Fehler gefunden und behoben." (oder: "Keine weiteren Fehler gefunden.")

Dieser zweite Pass ist NICHT optional und NICHT identisch mit Schritt 3. Schritt 3 prüft Vollständigkeit (sind alle Abschnitte da?). Schritt 4 prüft Korrektheit und Konsistenz (sind die Inhalte richtig, Links gültig, Diagramme aktuell?).

Dieser Prozess ist nicht optional. Dokumentationsverlust oder fehlerhafte Dokumentation durch unvollständige Arbeit ist inakzeptabel.

Wiki-Prinzip: Verlinkte Dokumentation (PFLICHT)

JEDE Erwähnung eines Hosts, Dienstes oder Systems in der Dokumentation MUSS als Markdown-Link auf dessen Dokumentation verweisen.

Dies gilt für ALLE Dokumentation - nicht nur Netzwerk, sondern auch Host-Dateien, Dependencies, Hardware, README, etc.

Regeln

1. Host-Referenzen → Link auf hosts/[hostname].md

   • Aus hosts/-Dateien: relativer Pfad [srvdocker02](srvdocker02.md)
   • Aus Root-Dateien: [srvdocker02](hosts/srvdocker02.md)
   • Aus Unterverzeichnissen: [srvdocker02](../hosts/srvdocker02.md)

2. Hardware-Referenzen → Link auf hardware/[gerät].md

   • [HPE Switch](hardware/hpe-switch.md) oder relativ [HPE Switch](../hardware/hpe-switch.md)

3. Dienst-/System-Referenzen → Link auf zugehörige Doku

   • Externe Repos: [Zabbix](https://gitea.egonetix.de/Egonetix/zabbix)
   • Interne Doku: [Keycloak SSO](keycloak-sso.md)

4. Mermaid-Diagramme: Hier sind keine Markdown-Links möglich. Stattdessen MUSS nach jedem Diagramm eine Referenz-Tabelle stehen mit Links zu den referenzierten Hosts/Diensten.

5. Tabellen: Host-/Dienstnamen in Tabellenzellen als Link formatieren.

6. Organisationsübergreifende Referenzen → Hosts/Dienste, die zu einer anderen Kunden-Organisation gehören, werden auf deren Gitea-Repo verlinkt.

   • Prinzip: Die kanonische Doku eines Hosts lebt in der Organisation, zu der er gehört. Andere Organisationen verweisen per Gitea-URL darauf.
   • Aus Egonetix auf Vinos-Host: [gw-nu-wan01](https://gitea.egonetix.de/Vinos/infrastructure/src/branch/main/hosts/gw-nu-wan01.md)
   • Aus Vinos auf Egonetix-Host: [srvhost04](https://gitea.egonetix.de/Egonetix/infrastructure/src/branch/main/hosts/srvhost04.md)
   • Lokaler Stub: Im eigenen Repo kann eine Stub-Datei existieren, die auf die kanonische Doku verweist (z.B. wenn der Host in der eigenen Infrastruktur referenziert wird). Der Stub muss klar als "Gehört zu Organisation X" markiert sein.
   • Wann: Immer wenn ein Host in der Doku einer anderen Organisation auftaucht (VPN-Gegenstellen, gemeinsame Dienste, Abhängigkeiten über Organisationsgrenzen).

Ausnahmen

• Derselbe Host innerhalb seiner eigenen Dokumentation (kein Self-Link)
• Hosts in der "Entdeckte aber nicht gescannte Hosts"-Liste (keine Doku vorhanden)
• Inline-Code-Blöcke (Befehle, Konfigurationen)

Beispiel

Falsch:

srvdocker02 benötigt srvdc01 für DNS.
PBS auf Hetzner Storage Box (1TB)

Richtig:

[srvdocker02](srvdocker02.md) benötigt [srvdc01](srvdc01.md) für DNS.
PBS auf Hetzner Storage Box (1TB) - siehe [srvhost04 Storage](srvhost04.md#hardware--storage)

Rolling Documentation: Opportunistisches Host-Scanning

Prinzip: Wenn du während deiner Arbeit Zugriff auf einen Host bekommst, führe einen VOLLSTÄNDIGEN Scan durch - nicht nur für die aktuelle Aufgabe.

Auslöser

• SSH-Zugriff auf einen Host
• Web-UI Zugriff (pfsense, NPM, etc.)
• API-Zugriff

Workflow bei Host-Zugriff

1. Prüfe: Existiert infrastructure/hosts/[hostname].md?
2. Falls nein oder unvollständig: Vollständigen Scan durchführen
3. Dann erst: Ursprüngliche Aufgabe erledigen

Scan-Checkliste nach Host-Typ

Netzwerk-Geräte (pfsense, Router):

• Interfaces (Name, IP, Netz)
• ALLE Firewall-Regeln (nicht nur relevante!)
• ALLE Aliases
• NAT-Regeln (Port-Forwards, Outbound)
• DHCP/DNS-Konfiguration
• System-Version
• ABHÄNGIGKEITEN: Welche Hosts/Dienste hängen von diesem Gerät ab?

Linux-Server:

• OS/Version
• Interfaces und IPs
• Laufende Dienste
• Docker-Container
• Offene Ports
• Wichtige Configs
• ABHÄNGIGKEITEN: Welche anderen Hosts braucht dieser Server? Wer braucht ihn?

Windows-Server:

• OS/Version
• Interfaces und IPs
• Dienste und geplante Tasks
• Installierte Rollen
• ABHÄNGIGKEITEN: Verbindungen zu anderen Systemen

PFLICHT: Abhängigkeiten dokumentieren

Bei JEDEM Host-Scan müssen die Abhängigkeiten erfasst werden:

Frage	Dokumentieren in
Welche Hosts/Dienste braucht dieser Host?	hosts/[host].md → Abschnitt "Abhängigkeiten"
Welche Hosts/Dienste hängen von diesem Host ab?	hosts/[host].md → Abschnitt "Abhängig von diesem Host"
Gibt es Abhängigkeitsketten?	dependencies.md → Mermaid-Diagramm

PFLICHT: Monitoring-Abgleich bei Infrastruktur-Änderungen

Wenn sich an einem Host Hardware, Software oder Dienste ändern, MUSS geprüft werden ob das Monitoring noch passt.

Dies gilt bei:

• Neuem Host/Dienst/Container hinzugefügt
• Host neuinstalliert oder migriert
• Dienst entfernt oder ersetzt
• Hardware-Änderung (Disk, RAM, Netz)
• Template-Wechsel in Zabbix

Prüf-Fragen:

Frage	Aktion wenn Ja
Wird dieser Host/Dienst überwacht?	Prüfen ob Items/Trigger noch aktuell sind
Wird er NICHT überwacht, sollte er aber?	→ Onboarding-Entscheidung treffen (siehe Zabbix copilot-instructions.md)
Wurden Dienste entfernt?	Phantom-Triggers/Items prüfen und ggf. löschen
Wurden neue Dienste hinzugefügt?	Template/Items ergänzen oder bewusst ausschließen
Hat sich die Rolle des Hosts geändert?	Host Groups, Service-Baum, Dependencies in Zabbix aktualisieren

Dokumentieren in:

• hosts/[host].md → Abschnitt "Monitoring" oder "Wiederkehrende Probleme"
• Zabbix README.md → "Nicht überwacht" Liste aktualisieren
• Zabbix copilot-instructions.md → Host-IDs Tabelle bei neuen Hosts

Ziel: Anhand der Dokumentation muss erkennbar sein:

• Was passiert wenn Host X ausfällt?
• Welche Dienste sind von Änderungen an Host X betroffen?
• Welche Hosts müssen vor Host X gestartet werden?

Beispiel Abhängigkeits-Dokumentation:

## Abhängigkeiten

Dieser Host benötigt:
- **srv-docker02** (10.10.10.81) - n8n Backend
- **srv-nu-dc01** (10.10.10.111) - DNS-Auflösung

## Abhängig von diesem Host

Folgende Dienste/Hosts sind von diesem Host abhängig:
- **flow.wvits.de** - Webhook-Zugang fällt aus wenn dieser Host down ist
- **n8n.vinos.de** - Interner Zugang über diesen NPM

## Impact bei Ausfall

| Ausfall-Szenario | Betroffene Dienste |
|------------------|-------------------|
| Komplett-Ausfall | flow.wvits.de, n8n.vinos.de, ... |
| Nur Port 443 | HTTPS-Zugriff auf alle proxied Dienste |

dependencies.md aktualisieren:

Nach jedem Host-Scan prüfen ob infrastructure/dependencies.md aktualisiert werden muss:

• Neue Abhängigkeitskette entdeckt? → Mermaid-Diagramm ergänzen
• Impact-Analyse hinzufügen
• Repo-Links aktualisieren

Für Vinos-Projekte gilt zusätzlich:

Der vollständige Monitoring-Workflow ist im Monitoring-Skill definiert:

• ~/Nextcloud/vinos/clawd/skills/monitoring/SKILL.md

Dieser Skill MUSS bei jeder Infrastruktur-Arbeit aufgerufen werden (analog zu verification-before-completion). Details siehe Skill-Dokumentation.

Beispiel

Aufgabe: Firewall-Regel für srv-revproxy01 prüfen

Falsch	Richtig
Nur die eine Regel prüfen	Erst: Existiert hosts/gw-nu-dmz02.md?
Session beenden	Nein → Vollständigen Scan aller Regeln, Aliases, Interfaces
	Host-Datei erstellen
	Dann: Ursprüngliche Aufgabe

Rekursive Host-Entdeckung (WICHTIG!)

Wenn du bei einem Scan Referenzen zu anderen Hosts siehst, gehe AUTOMATISCH weiter:

Entdeckungsquellen:

• Firewall-Regeln (Ziel-IPs, Aliases)
• NAT-Regeln (Forward-Ziele)
• DNS-Einträge
• Docker-Compose (externe Hosts)
• Konfigurationsdateien
• Log-Einträge
• Netzwerk-Verbindungen

Workflow:

Host A scannen
  ↓
Entdecke Referenz zu Host B (z.B. in Firewall-Regel)
  ↓
Kann ich Host B erreichen?
  ├─ JA → Host B scannen (rekursiv)
  └─ NEIN → Host B in Entdeckungsliste aufnehmen

Entdeckungsliste führen:

Wenn ein Host nicht gescannt werden kann (kein Zugriff, keine Credentials, etc.):

## Entdeckte aber nicht gescannte Hosts

| Host | IP | Entdeckt in | Grund für fehlenden Scan |
|------|----|-------------|-------------------------|
| srv-xyz01 | 10.10.10.99 | gw-nu-dmz02 Firewall-Regel | Kein SSH-Zugriff |
| db-server | 10.10.20.5 | docker-compose.yml | Credentials unbekannt |

Der User muss dich NICHT auf jeden Host einzeln hinweisen!

Du sollst selbstständig:

1. Referenzen zu anderen Hosts erkennen
2. Versuchen diese zu scannen
3. Falls nicht möglich: Dokumentieren was du entdeckt hast
4. Beim nächsten Mal nachfragen ob Zugriff jetzt möglich ist

Effizienz

Nutze parallele Agenten für umfangreiche Scans und rekursive Entdeckung.

Indirekt betroffene Hosts dokumentieren (PFLICHT)

Wenn du auf Host A arbeitest und dabei Host B konfigurierst (z.B. per SSH, API, DNS), gilt die Rolling-Documentation-Pflicht auch für Host B.

Dies ist eine häufige Fehlerquelle: Man dokumentiert nur den "Ziel-Host" der Aufgabe, vergisst aber die Hosts, auf denen man nebenbei Änderungen vorgenommen hat.

Beispiele:

Aufgabe auf Host A	Nebenarbeit auf Host B	Doku-Pflicht
ActiveSync auf srvmail01 einrichten	nginx-Config auf srvrevproxy02 anlegen	srvrevproxy02.md aktualisieren
Neue Subdomain für srvmail01	DNS-Record auf srvdc01 anlegen	srvdc01.md prüfen, domains.md ergänzen
Zertifikat für Dienst X	certbot auf srvrevproxy02 ausführen	srvrevproxy02.md aktualisieren
Spam-Learning einrichten	IMAP-Zugriff auf srvmail01 aktivieren	Abhängigkeit in dependencies.md ergänzen

Regel: Nach jeder SSH-Session auf einem Host fragen: "Habe ich die Doku dieses Hosts aktualisiert?"

Parallele Agenten-Nutzung (PFLICHT)

Claude MUSS eigenständig entscheiden, wie viele Agenten parallel gestartet werden, um Aufgaben schneller zu erledigen.

• Bis zu 10 oder mehr parallele Agenten sind erlaubt
• Claude entscheidet selbst, wie viele Agenten sinnvoll sind
• Unabhängige Teilaufgaben MÜSSEN parallel bearbeitet werden
• Dies gilt für: Host-Scans, Dokumentations-Updates, Verifikation, Recherche

Beispiele:

• 10 Host-Dateien aktualisieren → 10 Agenten parallel
• 5 unabhängige Recherche-Aufgaben → 5 Agenten parallel
• Scan + Dokumentation + Commit → sequentiell (abhängig)

Ausnahmen

• Zeitkritische Notfälle (erst fixen, dann dokumentieren)
• Explizite User-Anweisung nur aktuelle Aufgabe zu erledigen
• User sagt explizit "nicht weiter scannen"

Zabbix-Probleme beheben: Pflicht-Workflow

BEVOR Zabbix-Probleme behoben werden, MUSS immer zuerst ein Plan erstellt und dem User vorgelegt werden.

Phase A: Analyse (parallel, ohne User-Interaktion)

1. Alle offenen Probleme via API abfragen (problem.get)
2. Trigger-zu-Host-Mapping erstellen (trigger.get mit selectHosts)
3. Aktuelle Item-Werte prüfen (item.get — ist das Problem echt oder stale?)
4. Trigger-Expressions lesen (für korrekte Macro-Namen)

Phase B: Klassifizieren und Liste erstellen

Jedes Problem in eine Kategorie einordnen:

Kategorie	Beschreibung	Aktion
STALE	Trigger disabled, Event offen	manual_close setzen + Event schließen
THRESHOLD	Wert normal, Schwellwert zu niedrig	Host-Macro erstellen/anpassen
ECHT	Tatsächliches Problem	SSH-Intervention oder manuelle Aktion
TEMPLATE-NOISE	Trigger passt nicht zum Host-Typ	Trigger disablen oder Macro-Filter

Phase C: Nummerierte Liste dem User vorlegen

PFLICHT: Dem User eine nummerierte, nach Priorität sortierte Liste präsentieren:

# | Host | Problem | Kategorie | Geplante Aktion
1 | srvhost04 | Disk 95% | ECHT | SSH: Cleanup LXC 101
2 | srvdocker02 | Agent down | ECHT | SSH: Service starten
3 | gw-st01 | /mnt/share_new | STALE | API: FS-Macro + Event schließen
...

Der User entscheidet:

• Welche Punkte bearbeitet werden
• In welcher Reihenfolge
• Ob SSH-Aktionen gewünscht sind

Phase D: Punkt für Punkt abarbeiten

• Nur nach User-Freigabe ausführen
• Parallele Agenten für unabhängige API-Fixes
• Nach jedem Punkt: Ergebnis melden
• Ergebnis-Verifikation via problem.get

Phase E: Rolling Documentation aktualisieren (PFLICHT)

Nach JEDER Zabbix-Problem-Session:

1. Host-Dateien aktualisieren (infrastructure/hosts/[host].md):

   • Abschnitt "Wiederkehrende Probleme" anlegen/ergänzen
   • Datum, Problem, Lösung, ob wiederkehrend
   • Beispiel:

     ## Wiederkehrende Probleme
     
     | Datum | Problem | Lösung | Wiederkehrend |
     |-------|---------|--------|---------------|
     | 2026-01-29 | Memory >90% | Macro {$MEMORY.UTIL.MAX}=95 | Ja (normal für Workload) |
     | 2026-01-29 | Swap <50% free | Macro {$SWAP.PFREE.MIN.WARN}=10 | Ja (normal) |
     

2. Zabbix copilot-instructions.md aktualisieren:

   • Neue Pitfalls dokumentieren
   • Macro-Namen-Korrekturen festhalten
   • Patterns für zukünftige Problemlösung

3. dependencies.md prüfen — Falls neue Abhängigkeiten entdeckt

Wichtige Pitfalls

• Macro-Namen exakt prüfen! Trigger-Expression lesen, nicht raten. Beispiel: {$PVE.MEMORY.PUSE.MAX.WARN} ≠ {$PVE.MEM.PUSE.MAX.WARN}
• LLD-Trigger: Discovered Triggers können nicht direkt manual_close gesetzt werden. Stattdessen: Template Trigger-Prototyp updaten → LLD re-run (task.create type 6)
• Event schließen: Erst manual_close=1 auf Trigger setzen, dann event.acknowledge action=1
• curl | jq kann leere Ausgabe liefern: Immer erst in Datei speichern, dann lesen
• NIEMALS /etc/hosts editieren! DNS-Probleme werden IMMER auf dem zuständigen DNS-Server gelöst, nie auf dem Client. Keine Ausnahmen.
• Split-Horizon-DNS bei UCS: Wenn ein UCS-DC eine lokale Zone für eine öffentliche Domain hostet (z.B. egonetix.de), werden externe DNS-Einträge (z.B. auf INWX) nie erreicht — der DC antwortet autoritativ mit NXDOMAIN. Fix: Eintrag in der lokalen UCS-Zone per udm dns/host_record create anlegen. Bei jedem neuen externen Host prüfen ob ein lokaler DNS-Eintrag nötig ist.
• systemd-resolved: Vorsicht mit resolvectl domain: Das Setzen von DNS-Domains per resolvectl domain überschreibt DHCP-gelieferte Einstellungen komplett. Search-Domains (ohne ~) ermöglichen Kurzname-Auflösung (srvdocker02 → srvdocker02.egonetix.lan). Routing-Domains (mit ~) routen nur Queries an bestimmte DNS-Server, erlauben aber keine Kurzname-Auflösung. Beides mischen: resolvectl domain wlp0s20f3 egonetix.lan "~egonetix.de". Wichtig: Nach einem WLAN-Reconnect werden resolvectl-Änderungen von NetworkManager/DHCP wieder überschrieben — für permanente Änderungen die NetworkManager-Verbindung konfigurieren.
• Proxmox VM-ID-Wechsel: Wenn VMs umgezogen/neu erstellt werden, ALLE Zabbix-Referenzen prüfen: LLD-Items, Trigger, Actions, Scripts. Phantom-Items für alte VMIDs per item.delete entfernen.
• LXC-Container Swap-Monitoring: Auf LXC-Containern (Proxmox) Swap-Triggers generell disablen — Container haben keinen eigenen Swap und reporten den Host-Swap über /proc/swaps. Bei neuen LXC-Hosts immer prüfen.
• FreeBSD Agent-Spikes: pfSense/FreeBSD Zabbix-Agent kann kurzzeitig falsche Werte liefern (Uptime, Disk, Swap). Trigger mit min(,5m) statt last() härten um Einzelspitzen zu ignorieren.

Skills-Referenz

Skill	Zweck
/troubleshoot-host	Strukturierter Troubleshooting-Workflow
/session-end	Session beenden, Commits erstellen
/new-project	Neues Projekt anlegen
/delegate-remote	Tasks an Remote-Server delegieren (CRA)

---

Kanbanize (Businessmap) - Aufgabenverwaltung für Vinos

Instanz: https://weinvinosgmbh.kanbanize.com API v2 Basis-URL: https://weinvinosgmbh.kanbanize.com/api/v2/ Token-Speicherort (NICHT im Git-Sync!): ~/.config/kanbanize/token Geltungsbereich: Alle Arbeiten unter ~/Nextcloud/vinos/

Authentifizierung

curl -H "apikey: $(cat ~/.config/kanbanize/token)" \
  "https://weinvinosgmbh.kanbanize.com/api/v2/<endpoint>"

Bekannte Struktur

Ressource	ID	Name
Workspace	5	IT Abteilung
Board	1	Team Infrastruktur
User	4	Robert Wiegand

Pflicht-Workflow bei Vinos-Arbeiten

Bei JEDER Arbeit im Kontext ~/Nextcloud/vinos/ MUSS geprüft werden:

1. Karte suchen: Gibt es eine Kanbanize-Karte, die zur aktuellen Aufgabe passt?

   # Karten auf dem Board suchen
   curl -s -H "apikey: $(cat ~/.config/kanbanize/token)" \
     "https://weinvinosgmbh.kanbanize.com/api/v2/cards?board_ids=1&fields=card_id,title,section,column_name" | jq .
   

2. Kommentar vorbereiten: Falls eine passende Karte existiert, eine Dokumentation der Problembehandlung/Lösung als Kommentar formulieren.

3. User-Freigabe einholen: Den vorbereiteten Kommentar dem User vorlegen und auf explizites OK warten.

4. Erst nach Freigabe posten:

   curl -s -X POST -H "apikey: $(cat ~/.config/kanbanize/token)" \
     -H "Content-Type: application/json" \
     -d '{"text":"<Kommentar>"}' \
     "https://weinvinosgmbh.kanbanize.com/api/v2/cards/<card_id>/comments"
   

WICHTIG: Keine eigenmächtigen Aktionen

Du darfst in Kanbanize NICHTS eigenmaechtig aendern. Fuer JEDE Aktion ist die explizite Freigabe des Users erforderlich:

• Kommentare schreiben → User-OK abwarten
• Karten verschieben → User-OK abwarten
• Karten erstellen → User-OK abwarten
• Karten bearbeiten → User-OK abwarten
• Jede andere Schreiboperation → User-OK abwarten

Lesen/Suchen ist jederzeit erlaubt — nur Schreiboperationen erfordern Freigabe.

Kommentar-Format für Problemdokumentation

WICHTIG: Kanbanize-Kommentare ignorieren \n-Zeilenumbrüche! Formatierung MUSS über HTML-Tags erfolgen: <br> für Zeilenumbrüche, <b> für Fettschrift,   für Einrückung. Die API gibt immer type: plain zurück, rendert aber trotzdem HTML.

Template (HTML):

<b>[TITEL: Kurzbeschreibung]</b><br><br><b>PROBLEM</b><br>• [Punkt 1]<br>• [Punkt 2]<br><br><b>URSACHE</b><br>• [Ursache 1]<br>• [Ursache 2]<br><br><b>LÖSUNG</b><br>• [Maßnahme 1]<br>• [Maßnahme 2, mit Unterpunkten:]<br>&nbsp;&nbsp;&nbsp;&nbsp;◦ [Detail 1]<br>&nbsp;&nbsp;&nbsp;&nbsp;◦ [Detail 2]<br><br><b>BETROFFENE SYSTEME</b><br>• [Host/Dienst 1]<br>• [Host/Dienst 2]

Formatierungs-Regeln:

Element	HTML	Ergebnis
Zeilenumbruch	<br>	Neue Zeile
Leerzeile	<br><br>	Absatz
Fettschrift	<b>Text</b>	Text
Einrückung	&nbsp;&nbsp;&nbsp;&nbsp;	4 Leerzeichen
Aufzählung	• Text (Unicode U+2022)	• Text
Unter-Aufzählung	◦ Text (Unicode U+25E6)	◦ Text

Inhaltliche Anforderungen

Kommentare müssen genug Detail enthalten, um bei Problemen als Troubleshooting-Einstieg zu dienen.

• Bei jeder Erwähnung eines Dienstes/Protokolls die konkreten Verbindungsdaten angeben (Host, Port, Protokoll)
• Nicht: "per SMTP verschickt" → Sondern: "per SMTP über smtp.mailbox.org:465 (SSL/TLS) verschickt"
• Nicht: "IMAP-Abruf" → Sondern: "IMAP IDLE auf imap.mailbox.org:993 (TLS)"
• Nicht: "auf dem Server" → Sondern: "auf srv-docker02 (/home/vinosadmin/n8n/)"
• Pfade, IPs, Ports, Credentials-Quellen immer mit angeben
• Ziel: Jemand der den Kommentar liest, weiß sofort wo er nachschauen muss wenn etwas nicht funktioniert

User taggen (@Mention)

@Vorname Nachname im Kommentartext wird automatisch als Mention erkannt — kein spezieller API-Parameter nötig. Kanbanize wandelt es in <strong id="mention-..."> um und der User erhält eine Benachrichtigung.

Karten verschieben

curl -s -X PATCH -H "apikey: $(cat ~/.config/kanbanize/token)" \
  -H "Content-Type: application/json" \
  -d '{"column_id": <COLUMN_ID>}' \
  "https://weinvinosgmbh.kanbanize.com/api/v2/cards/<CARD_ID>"

Bekannte Column-IDs (Board 1):

Column-ID	Name	Section
1	Aufgaben Backlog	Backlog
2	ToDo	Requested
3	In Bearbeitung	In Progress
4	Erledigt	Done
5	Ready to Archive	Archive

Achtung: Wenn alle Child-Karten einer Parent-Karte auf "Done" stehen, wird die Parent-Karte automatisch mit verschoben.

Pitfalls

• Kommentare können NICHT gelöscht werden — weder via API noch UI. Workaround: Inhalt durch . ersetzen
• \n wird komplett ignoriert — immer <br> verwenden
• Markdown wird NICHT gerendert — kein ##, **, - etc.
• type ist immer plain — kann nicht auf html gesetzt werden, HTML wird trotzdem gerendert

In die Task-Abschluss-Checkliste integriert

Bei Vinos-Arbeiten wird die Kanbanize-Prüfung Teil der Pflicht-Checkliste:

• Kanbanize geprüft? Passende Karte gesucht?
• Kommentar vorbereitet? Falls Karte existiert: Doku dem User vorgelegt?
• User-Freigabe erhalten? Erst nach OK posten

---

Claude Remote Agent (CRA) - Verteilte Task-Ausführung

Repository: ~/Nextcloud/egonetix/claude-remote-agent CLI-Tool: cra Zweck: Delegiert Aufgaben an Remote-Server, die Claude Code CLI autonom ausführen - auch wenn der Laptop offline ist.

Architektur

Laptop (Coordinator)  ──SSH + JSON-RPC 2.0──>  Server (claude-agent)

• Coordinator: Verwaltet Server, erstellt Tasks, sammelt Ergebnisse
• Agent: Empfängt Tasks, führt Claude Code CLI autonom aus, speichert Ergebnisse lokal
• Persistenz: SQLite auf beiden Seiten, Tasks überleben Verbindungsabbrüche

Wann CRA vorschlagen

Du SOLLST dem User CRA aktiv vorschlagen, wenn:

Szenario	Beispiel
Lang laufende Tasks	Codebase-Analyse, Refactorings, Log-Analyse
Server-Wartung	Updates, Cleanup, Security-Audits
Multi-Server-Operationen	Gleiche Aufgabe auf mehreren Servern parallel
Offline-Delegation	User will Laptop zuklappen, Tasks sollen weiterlaufen
Unabhängige Teilaufgaben	Aufgabe lässt sich in parallele Sub-Tasks aufteilen

"Diese Aufgabe eignet sich gut für CRA - soll ich sie an einen Remote-Server delegieren?"

Kommando-Referenz

# Server verwalten
cra servers add <name> <host> [--user USER] [--port PORT] [--key PATH] [--tag TAG]
cra servers list [--all]
cra servers remove <name> [--yes]
cra servers status [name]

# Tasks
cra submit <server> "<prompt>" [--priority N] [--model MODEL] [--max-turns N]
cra status <server> [task_id]
cra cancel <server> <task_id>

# Ergebnisse
cra collect [server] [--task ID] [--since ISO-DATETIME] [--output FILE]

# Config synchronisieren
cra sync-config [server] [--no-claude-md] [--no-settings]

MCP-Server Integration

Wenn der CRA MCP-Server konfiguriert ist, stehen CRA-Funktionen als native Tools zur Verfügung (cra_submit, cra_status, cra_collect, cra_servers_list, cra_server_status, cra_sync_config). Prüfe ob MCP-Tools verfügbar sind, bevor du auf CLI-Befehle zurückfällst.

Wichtige Hinweise

• Autonome Ausführung: Server brauchen ~/.claude/settings.json mit Tool-Permissions
• Config-Sync: Nach CLAUDE.md/settings.json Änderungen → cra sync-config
• Retry: Fehlgeschlagene Tasks werden automatisch wiederholt (max 3x)