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?**
  ```bash
  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

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

---

## Auto-Memory NICHT nutzen

**Projekt-spezifische Erkenntnisse gehoeren in die `CLAUDE.md` oder `copilot-instructions.md` des jeweiligen Repos**, damit sie in Git versioniert und gepusht werden. Die `~/.claude/projects/*/memory/`-Verzeichnisse sind rein lokal und gehen bei Rechner-Neuaufsetzen verloren.

- Neue Erkenntnisse → `CLAUDE.md` im Projekt-Repo
- NICHT in `~/.claude/projects/*/memory/MEMORY.md` schreiben

---

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

---

## Model Selection Strategy

**Core Principle:** Avoid context loss between models. Using a cheaper model for execution and a more expensive model for error recovery costs more in total tokens than using the appropriate model from the start.

### Decision Tree

**1. Trivial, read-only tasks (zero risk)?**
   - Examples: `git status`, checking if a file exists, reading a single file
   - **Use: HAIKU**
   - Rationale: Fastest, cheapest, no context needed, no execution risk

**2. Standard task with a clear plan?**
   - **Default: OPUS (plans AND executes in one shot)**
   - **Rare Exception: SONNET for execution-only IF:**
     - Plan is 100% mechanical (no decisions needed, pure step-following)
     - AND error probability is extremely low (documented, tested system)
     - AND the cost saving actually matters for the specific task
   - Rationale: Opus adapts on-the-fly, handles surprises without re-planning overhead

**3. Complex, risky, or unknown-territory tasks?**
   - Examples: Host infrastructure scans, service restarts, SSH operations, debugging, anything with potential for surprises
   - **Use: OPUS**
   - Rationale: Lowest error rate, best context understanding, avoids costly error recovery

### Why This Matters: Context Loss is Expensive

**Anti-pattern: Model Switching**
```
Opus plans → Sonnet/Haiku executes → Reality differs → Opus must blind-debug
= Token cost: Plan tokens + Execution tokens + Error recovery tokens
```

**Better: One-shot Opus**
```
Opus plans AND executes, adapts on-the-fly, handles surprises
= Token cost: Plan tokens + Execution tokens (no re-planning overhead)
```

**Real-world execution rarely matches plans exactly** because:
- Unexpected file structures or permissions
- System state differences from documentation
- Commands that succeed but produce different output
- Permission errors or authentication issues
- Configuration differences in different environments

When Opus executes the plan, it can adapt in real-time without:
- Losing context between model switches
- Re-explaining the situation to a different model
- Incurring planning overhead again

### Concrete Examples

| Task | Model | Reasoning |
|------|-------|-----------|
| `git status` | HAIKU | Read-only, no execution risk |
| Read a config file | HAIKU | Read-only, no execution risk |
| Host infrastructure scan | OPUS | Complex, multiple hosts, recursive discovery, adapts to surprises |
| Service restart | OPUS | Risk of unexpected state, error handling needed |
| SSH operations | OPUS | Unknown system state, permission issues possible |
| Codebase refactoring | OPUS | Multiple files, architectural decisions, error recovery critical |
| Deployment script (well-tested) | SONNET (rare) | Only if plan is 100% mechanical AND low error risk AND cost matters |
| Debugging a production issue | OPUS | Unknown territory, needs real-time adaptation |
| DNS record check | HAIKU | Read-only lookup |
| Firewall rule modification | OPUS | Complex state, multiple systems affected, documentation updates needed |
| Running documented commands | SONNET (rare) | Only if commands are proven, output predictable, error probability <1% |

### Anti-Patterns to Avoid

| Anti-Pattern | Why It Fails | Cost |
|--------------|-------------|------|
| Use Haiku/Sonnet to "save tokens" | Failures cost more in error recovery | ❌ False economy |
| Plan with Opus, execute with Haiku, fix errors with Opus | Context loss between models | ❌ Most expensive option |
| Sonnet for everything "to balance speed/cost" | Unclear when it's appropriate | ❌ Inconsistent, risky |
| Switch models mid-task based on "looking easy" | Real execution rarely matches expectations | ❌ Context loss |

### When in Doubt

**Default to OPUS.** Token cost of unnecessary Opus usage is typically less than the token cost of error recovery with a cheaper model. Better to overshoot on capability than to undershoot and pay for recovery.

---

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

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

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

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

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

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

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

**Workflows auf Board 1:**

| Workflow-ID | Name | Zweck |
|-------------|------|-------|
| 1 | Aufgaben | Operative Tasks (Backlog → ToDo → In Bearbeitung → Erledigt) |
| 2 | Themen | Übergeordnete Themen/Epics, Parent-Karten für Aufgaben |

**Columns & Lanes — Workflow 1 (Aufgaben):**

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

| Lane-ID | Name |
|---------|------|
| 1 | Default (Aufgaben) |

**Columns & Lanes — Workflow 2 (Themen):**

| Column-ID | Name | Section |
|-----------|------|---------|
| 29 | Themen Backlog | Backlog |
| 8 | Requested | Requested |
| 9 | In Progress | In Progress |
| 10 | Ready to Archive | Done/Archive |

| Lane-ID | Name |
|---------|------|
| 5 | Default (Themen) |

### 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?
   ```bash
   # 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:**
   ```bash
   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, `&nbsp;` für Einrückung.
Die API gibt immer `type: plain` zurück, rendert aber trotzdem HTML.

**Template (HTML):**

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

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

**Column-IDs:** Siehe "Bekannte Struktur" oben für vollständige Auflistung beider Workflows.

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

### Karten erstellen (Aufgaben-Workflow)

**Hintergrund:** Workflow 1 (Aufgaben) hat eine Arrival Rule, die verlangt, dass jede Karte mit einem Thema (Parent im Themen-Workflow 2) verknüpft ist. Direkte Kartenerstellung in Workflow 1 per API schlägt daher fehl.

**Workaround:** Karte zunächst in Workflow 2 (Themen) erstellen, Parent-Link setzen, dann nach Workflow 1 verschieben.

#### Workflow A — Thema existiert bereits

```bash
# 1. Karte in Workflow 2 erstellen (Themen Backlog)
NEW_ID=$(curl -s -X POST -H "apikey: $(cat ~/.config/kanbanize/token)" \
  -H "Content-Type: application/json" \
  -d '{"board_id": 1, "workflow_id": 2, "lane_id": 5, "column_id": 29, "title": "Neue Aufgabe"}' \
  "https://weinvinosgmbh.kanbanize.com/api/v2/cards" | jq -r '.data.card_id')

# 2. Parent-Link zum existierenden Thema setzen
curl -s -X PUT -H "apikey: $(cat ~/.config/kanbanize/token)" \
  "https://weinvinosgmbh.kanbanize.com/api/v2/cards/$NEW_ID/parents/<THEMA_ID>"

# 3. Nach Aufgaben ToDo verschieben + Titel/Owner setzen
curl -s -X PATCH -H "apikey: $(cat ~/.config/kanbanize/token)" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": 1, "column_id": 2, "lane_id": 1, "owner_user_id": 4}' \
  "https://weinvinosgmbh.kanbanize.com/api/v2/cards/$NEW_ID"
```

#### Workflow B — Thema existiert noch nicht

```bash
# 1. Thema in Workflow 2 erstellen
THEMA_ID=$(curl -s -X POST -H "apikey: $(cat ~/.config/kanbanize/token)" \
  -H "Content-Type: application/json" \
  -d '{"board_id": 1, "workflow_id": 2, "lane_id": 5, "column_id": 29, "title": "Neues Thema"}' \
  "https://weinvinosgmbh.kanbanize.com/api/v2/cards" | jq -r '.data.card_id')

# 2. Kind-Karte in Workflow 2 erstellen
CHILD_ID=$(curl -s -X POST -H "apikey: $(cat ~/.config/kanbanize/token)" \
  -H "Content-Type: application/json" \
  -d '{"board_id": 1, "workflow_id": 2, "lane_id": 5, "column_id": 29, "title": "Aufgabe zum Thema"}' \
  "https://weinvinosgmbh.kanbanize.com/api/v2/cards" | jq -r '.data.card_id')

# 3. Parent-Link setzen
curl -s -X PUT -H "apikey: $(cat ~/.config/kanbanize/token)" \
  "https://weinvinosgmbh.kanbanize.com/api/v2/cards/$CHILD_ID/parents/$THEMA_ID"

# 4. Kind-Karte nach Aufgaben ToDo verschieben
curl -s -X PATCH -H "apikey: $(cat ~/.config/kanbanize/token)" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": 1, "column_id": 2, "lane_id": 1, "owner_user_id": 4}' \
  "https://weinvinosgmbh.kanbanize.com/api/v2/cards/$CHILD_ID"
```

### 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
- **Arrival Rule auf Workflow 1** blockiert direkte Kartenerstellung per API — Workaround: Karte in Workflow 2 erstellen, Parent setzen, dann nach Workflow 1 verschieben (siehe "Karten erstellen")
- **Parent-Link Endpunkt:** `PUT /cards/{id}/parents/{parent_id}` — nicht POST, nicht PATCH. Entfernen: `DELETE /cards/{id}/parents/{parent_id}`
- **`linkedCards` Sub-Resource ist read-only** — nur GET, keine Manipulation darüber möglich. Parent/Child-Links über `/parents/` und `/children/` Endpunkte verwalten

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

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