# 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?
    - `infrastructure/dependencies.md` aktualisiert?
  - Änderungen committet und gepusht?

### Bei JEDEM Task-Abschluss:

- [ ] **Alle Änderungen committet und gepusht?**
  - Aktuelles Repo
  - Infrastructure-Repo (falls relevant)

- [ ] **Settings-Sync geprüft?**
  ```bash
  cd ~/dotfiles/claude_settings && git fetch origin && git status
  ```

### ⚠️ 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

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

Falls Änderungen vorhanden:
```bash
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

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

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

```markdown
# 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:

```bash
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:

```markdown
## 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:
```bash
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:**

   ```bash
   # Git initialisieren (falls nicht vorhanden)
   git init
   git branch -M main

   # Template aus infrastructure/_templates/ kopieren
   ```

3. **Repo auf Gitea erstellen (API):**
   ```bash
   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:**
   ```bash
   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:**
```bash
# 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:**
```bash
# 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

```bash
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:

```markdown
| 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:

```markdown
| # | 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."**

**Dieser Prozess ist nicht optional.** Dokumentationsverlust 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 |

**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:**

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

#### 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.):

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

### 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:
     ```markdown
     ## 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

### 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) |

---

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

```bash
# 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)