feat: Beratungsumgebung (CLAUDE.md, Skills finanz-api/finanzberatung/auszug-import)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.claude/skills/auszug-import/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: auszug-import
+description: Workflow zur Betreuung von Kontoauszugs-Importen (Inbox scannen, Entwürfe prüfen, Vorschau zusammenfassen, bestätigen) sowie zum Beheben von Parser-Fehlern im Tool-Repo ~/bin/finance. Use when neue PDF-Kontoauszüge importiert werden sollen, ein Import in der Vorschau (draft) auf Bestätigung wartet, oder ein Import mit Fehlerstatus (error) fehlgeschlagen ist und der Parser angepasst werden muss.
+---
+
+# Auszug-Import betreuen
+
+## 1. Status prüfen
+
+```bash
+KEY=$(grep '^FB_API_KEY=' /home/wlfb/bin/finance/.env | cut -d= -f2)
+curl -s -H "Authorization: Bearer $KEY" http://127.0.0.1:8096/api/imports | jq
+```
+
+Falls neue PDFs in der Inbox liegen könnten (`~/.local/share/finance_pod/data/inbox/`),
+zuerst neu einscannen:
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $KEY" http://127.0.0.1:8096/api/imports/scan-inbox | jq
+```
+
+Auf Status `draft` (wartet auf Bestätigung) und `error` (Parser
+fehlgeschlagen) filtern.
+
+## 2. Drafts: Vorschau prüfen und bestätigen
+
+```bash
+curl -s -H "Authorization: Bearer $KEY" \
+  http://127.0.0.1:8096/api/imports/<id>/preview | jq
+```
+
+Dem Nutzer zusammenfassen: Zeitraum, Anzahl Buchungen, Saldo-Check
+(`balance_ok`), Zahl der erkannten Duplikate. Erst nach ausdrücklicher
+Bestätigung durch den Nutzer:
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $KEY" \
+  http://127.0.0.1:8096/api/imports/<id>/confirm | jq
+```
+
+Nie blind übernehmen — auch bei `balance_ok: true` dem Nutzer die Eckdaten
+vorlegen.
+
+## 3. Parser-Fehler beheben
+
+Bei Status `error` (`error_message` beachten) liegt die Original-PDF weiterhin
+in der Inbox. Vorgehen im Tool-Repo `/home/wlfb/bin/finance`:
+
+1. PDF-Text ansehen, um Regexe abzugleichen:
+   ```bash
+   cd /home/wlfb/bin/finance && .venv/bin/python scripts/dump_pdf_text.py \
+     ~/.local/share/finance_pod/data/inbox/<datei>.pdf
+   ```
+2. Regex-Konstanten im passenden Parser fixen — je nach Bank
+   `app/parsers/vr.py`, `app/parsers/hvb.py` oder `app/parsers/dkb.py`
+   (Bank-Erkennung in `app/parsers/detect.py`, gemeinsames Interface in
+   `app/parsers/base.py`).
+3. Tests laufen lassen:
+   ```bash
+   cd /home/wlfb/bin/finance && .venv/bin/python -m pytest -q
+   ```
+4. Image neu bauen und Pod neu aufsetzen, damit die Parser-Änderung im
+   laufenden Container wirksam wird:
+   ```bash
+   cd /home/wlfb/bin && ./create_pod_finance.sh
+   ```
+5. Import erneut anstoßen (`scan-inbox` bzw. erneuter Upload) und Vorschau
+   wie unter Schritt 2 prüfen.
+
+## Grundregeln (siehe auch CLAUDE.md)
+
+- Importe immer über die Vorschau bestätigen lassen, nie blind übernehmen.
+- Echte, bereits bestätigte Buchungen nicht anfassen — nur Entwürfe/Importe
+  in diesem Workflow bearbeiten.

.claude/skills/finanz-api/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: finanz-api
+description: Referenz aller REST-Endpunkte des Finanzberatungs-Tools (Konten, Buchungen, Kategorien, Regeln, Importe, wiederkehrende/geplante Posten, Kredite, Szenarien) mit curl-Beispielen. Use when Claude Code Daten aus dem Finanzberatungs-Tool lesen oder schreiben soll — Konten/Salden abfragen, Buchungen filtern/anlegen/korrigieren, Importe verwalten, Planungsposten oder Szenarien anlegen und durchrechnen.
+---
+
+# Finanz-API
+
+REST/JSON unter `http://127.0.0.1:8096/api/…`, vollständig dokumentiert unter
+`http://127.0.0.1:8096/docs` (OpenAPI/Swagger). Alle Endpunkte erfordern den
+Header `Authorization: Bearer <FB_API_KEY>`.
+
+## Key extrahieren
+
+```bash
+KEY=$(grep '^FB_API_KEY=' /home/wlfb/bin/finance/.env | cut -d= -f2)
+```
+
+Verwende `$KEY` in allen folgenden Beispielen. Den Key niemals ausgeben,
+loggen oder in Antworten an den Nutzer wiederholen.
+
+## Konten (`/api/accounts`)
+
+`GET` (Liste inkl. aktuellem Saldo je Konto), `GET /{id}`, `POST` (Konto
+anlegen: `bank`, `iban`, `name`, `type`).
+
+```bash
+curl -s -H "Authorization: Bearer $KEY" http://127.0.0.1:8096/api/accounts | jq
+```
+
+## Buchungen (`/api/transactions`)
+
+`GET` mit Filtern `account_id`, `date_from`, `date_to`, `category_id`, `q`
+(Volltext auf Verwendungszweck/Gegenpartei), `status` (Default `confirmed`),
+`limit`/`offset`. `POST` legt eine Buchung manuell an (`force: true`
+überschreibt die Duplikat-Prüfung). `PATCH /{id}` ändert **nur**
+`category_id` — echte Buchungen sonst nie verändern.
+
+```bash
+curl -s -H "Authorization: Bearer $KEY" \
+  "http://127.0.0.1:8096/api/transactions?date_from=2026-01-01&category_id=3&limit=50" | jq
+```
+
+## Kategorien & Regeln (`/api/categories`, `/api/category-rules`)
+
+`GET`/`POST /api/categories` (`name`). `GET`/`POST /api/category-rules`
+(`pattern`, `category_id`, `priority`) und `DELETE /api/category-rules/{id}`.
+Regeln kategorisieren künftige Importe automatisch.
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
+  -d '{"pattern": "REWE", "category_id": 3, "priority": 50}' \
+  http://127.0.0.1:8096/api/category-rules | jq
+```
+
+## Importe (`/api/imports`)
+
+`POST /upload` (multipart, PDF), `POST /scan-inbox` (scannt die Inbox neu),
+`GET` (Liste mit Status `draft`/`confirmed`/`error`), `GET /{id}/preview`
+(Buchungen + Saldo-Check + Duplikat-Zahl), `POST /{id}/confirm`
+(übernimmt die Vorschau endgültig), `DELETE /{id}`.
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $KEY" \
+  http://127.0.0.1:8096/api/imports/scan-inbox | jq
+```
+
+## Wiederkehrende Posten (`/api/recurring`)
+
+`GET`/`POST` (`name`, `amount`, `rhythm`, `due_day`, `start_date`,
+`end_date`, `category_id`), `PATCH`/`DELETE /{id}`, sowie
+`GET /recurring/suggestions` (Muster-Erkennung aus importierten Buchungen).
+
+```bash
+curl -s -H "Authorization: Bearer $KEY" \
+  http://127.0.0.1:8096/api/recurring/suggestions | jq
+```
+
+## Geplante Einmalposten (`/api/planned`)
+
+`GET`/`POST` (`name`, `amount`, `due`, `category_id`), `PATCH`/`DELETE /{id}`.
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
+  -d '{"name": "Zahnarzt", "amount": -450.00, "due": "2026-09-01"}' \
+  http://127.0.0.1:8096/api/planned | jq
+```
+
+## Kredite (`/api/loans`)
+
+`GET`/`POST` (`name`, `principal`, `annual_rate_pct`, `term_months`,
+`payout_date`, `repayment_type`: `annuity`|`bullet`), `PATCH`/`DELETE /{id}`,
+`GET /{id}/schedule` (Tilgungsplan: Rate, Zins, Tilgung, Restschuld je Termin).
+
+```bash
+curl -s -H "Authorization: Bearer $KEY" \
+  http://127.0.0.1:8096/api/loans/1/schedule | jq
+```
+
+## Szenarien (`/api/scenarios`)
+
+`GET`/`POST` (`name`, `description`, `include_recurring`, `include_planned`),
+`PATCH`/`DELETE /{id}`. Kredit zuordnen: `POST`/`DELETE
+/{id}/loans/{loan_id}`. Modifikator hinzufügen: `POST /{id}/modifiers` mit
+`target_type` (`category`|`recurring`), `target_id`, `kind`
+(`percent`|`absolute`|`remove`), `value`; löschen über `DELETE
+/{id}/modifiers/{mod_id}`.
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
+  -d '{"name": "Basis-Szenario"}' \
+  http://127.0.0.1:8096/api/scenarios | jq
+```
+
+## Durchrechnen (`/api/scenarios/{id}/project`)
+
+`POST`, optionale Query-Parameter `horizon_days` und `start_date`. Antwort:
+`low_point_date`, `low_point_balance`, `below_zero_date`,
+`below_threshold_date`, `series` (Tagesreihe Datum/Saldo).
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $KEY" \
+  "http://127.0.0.1:8096/api/scenarios/1/project?horizon_days=180" | jq
+```

.claude/skills/finanzberatung/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: finanzberatung
+description: Fünf-Schritte-Workflow für Finanzberatung mit dem Finanzberatungs-Tool — Lage erfassen, Basis-Szenario, Varianten (Kredit/Kürzungen) durchrechnen, vergleichen, Empfehlung mit Zahlen begründen. Use when der Nutzer eine Finanzeinschätzung, Kreditberatung, Sparempfehlung oder Liquiditätsplanung ("reicht das Geld", "brauche ich einen Kredit", "wo kann ich kürzen") anfragt.
+---
+
+# Finanzberatung
+
+Beratung erfolgt datengetrieben über das Finanzberatungs-Tool (Skill
+`finanz-api` für die API-Details). Kein Rat ohne durchgerechnetes Szenario.
+
+## 1. Lage erfassen
+
+- Konten und aktuelle Salden abrufen (`GET /api/accounts`).
+- Unkategorisierte bzw. auffällige Buchungen prüfen (`GET /api/transactions`
+  ohne `category_id`-Filter bzw. mit `q`), damit Auswertungen nach Kategorie
+  belastbar sind.
+- Prüfen, ob wiederkehrende Posten gepflegt sind (`GET /api/recurring`); falls
+  lückenhaft, `GET /api/recurring/suggestions` durchgehen und mit dem Nutzer
+  bestätigen/verwerfen, bevor weitergerechnet wird.
+
+## 2. Basis-Szenario anlegen/durchrechnen
+
+- Falls noch nicht vorhanden: Basis-Szenario anlegen (`POST /api/scenarios`,
+  ohne Modifikatoren, mit vorhandenen wiederkehrenden/geplanten Posten).
+- Durchrechnen (`POST /api/scenarios/{id}/project`) und Ergebnis als
+  Referenzlinie festhalten (Tiefpunkt, Unterschreitungsdatum falls vorhanden).
+
+## 3. Fragestellung in Varianten übersetzen
+
+- Kreditbedarf: Kredit anlegen (`POST /api/loans` mit Betrag, Zinssatz,
+  Laufzeit, Auszahlungsdatum, Tilgungsart) und dem Szenario zuordnen
+  (`POST /api/scenarios/{id}/loans/{loan_id}`).
+- Kürzungspotenzial: Modifikatoren je Kategorie oder wiederkehrendem Posten
+  anlegen (`POST /api/scenarios/{id}/modifiers`, `target_type`
+  `category`|`recurring`, `kind` `percent`|`absolute`|`remove`).
+- Für jede Fragestellung ein eigenes Szenario (Kopie der Idee, nicht das
+  Basis-Szenario verändern), damit Varianten unabhängig vergleichbar bleiben.
+
+## 4. Varianten durchrechnen
+
+- Jede Variante mit `POST /api/scenarios/{id}/project` (gleicher Horizont wie
+  das Basis-Szenario, damit die Vergleichswerte konsistent sind) durchrechnen.
+- Bei Kredit-Varianten zusätzlich den Tilgungsplan ziehen
+  (`GET /api/loans/{id}/schedule`) für Gesamtzinskosten und Ratenhöhe.
+
+## 5. Vergleichen und Empfehlung formulieren
+
+- Vergleichstabelle je Variante: Tiefpunkt (Datum + Betrag),
+  Unterschreitungsdatum (Null bzw. Warnschwelle), bei Krediten
+  Gesamtzinskosten und monatliche Rate aus dem Tilgungsplan.
+- Empfehlung immer mit diesen Zahlen begründen, nicht nur qualitativ.
+- Hinweis an den Nutzer: Das Grafana-Dashboard „Szenario-Vergleich“
+  (http://127.0.0.1:8097) zeigt die Verlaufskurven der Varianten übereinander
+  mit Nulllinie und Warnschwelle — für die visuelle Gegenprobe verlinken bzw.
+  empfehlen, dort nachzusehen.
+
+## Grundregeln (siehe auch CLAUDE.md)
+
+- Echte, bestätigte Buchungen nie ändern — Korrekturen nur als
+  Kategorie-Anpassung.
+- Zukunftsplanung ausschließlich über Szenarien, nie am Basis-Datenbestand.

CLAUDE.md

@@ -0,0 +1,18 @@
+# Finanzberatungs-Umgebung
+
+Beratung und Auswertung laufen auf Deutsch.
+
+## Finanzberatungs-Tool
+- API + Web-GUI: http://127.0.0.1:8096 (OpenAPI: /docs), Grafana: http://127.0.0.1:8097
+- API-Key: `FB_API_KEY` in `/home/wlfb/bin/finance/.env` (Header `Authorization: Bearer <key>`)
+- Quellcode/Betrieb: Repo `/home/wlfb/bin` (Pod `finance_pod`,
+  `systemctl --user status pod-finance_pod.service`)
+- Import-Inbox (PDFs hier ablegen): `~/.local/share/finance_pod/data/inbox/`
+
+## Grundregeln
+- Echte (bestätigte) Buchungen niemals ändern oder löschen — Korrekturen nur
+  als Kategorie-Anpassung; Zukunftsplanung ausschließlich über Szenarien.
+- Importe immer über die Vorschau bestätigen lassen, nie blind übernehmen.
+- Empfehlungen (Kredit, Kürzungen) stets mit durchgerechneten Szenarien und
+  Zahlen (Tiefpunkt, Unterschreitungs-Datum, Ratenhöhe) begründen.
+- Für API-Nutzung den Skill `finanz-api` verwenden.