docs: add ARCHITECTURE.md & ARCHITECTURE_QUICK.md, fix user pre bg

- ARCHITECTURE.md: comprehensive project documentation (868 lines) covering all 21 chapters (data model, services, endpoints, chat pipeline, tool system, agents, memory, skills, telegram, cronjobs, krea, auth, workspace, deployment, config) - ARCHITECTURE_QUICK.md: compact quick-reference (223 lines) for fast lookups during development - chat.css: add .msg.user.markdown pre selector so code blocks in user messages get correct background color (was only on code)
2026-03-04 20:43:14 +01:00
1 parent 26da25967d
commit 4e915f76af
@@ -0,0 +1,868 @@
+# ARCHITECTURE.md – Gott
+
+**Gott** ist eine selbst-gehostete AI-Chat-Plattform, gebaut auf **.NET 10** und der **Anthropic Claude API**. Sie bietet Multi-User-Support, persistente Agent-Memory, Datei-/Shell-Tools, Telegram-Integration, Cronjobs und eine Krea-Bildgenerierung – alles über ein Vanilla-JavaScript-Frontend gesteuert.
+
+---
+
+## Inhaltsverzeichnis
+
+1. [Überblick](#überblick)
+2. [Tech-Stack](#tech-stack)
+3. [Projektstruktur](#projektstruktur)
+4. [Datenmodell](#datenmodell)
+5. [Backend-Architektur](#backend-architektur)
+   - [Program.cs – Startup](#programcs--startup)
+   - [Services](#services)
+   - [Endpoints (API)](#endpoints-api)
+   - [Middleware](#middleware)
+   - [Models](#models)
+   - [Templates](#templates)
+6. [Frontend-Architektur](#frontend-architektur)
+7. [Chat-Pipeline](#chat-pipeline)
+8. [Tool-System](#tool-system)
+9. [Agent-System](#agent-system)
+10. [System-Prompt-Aufbau](#system-prompt-aufbau)
+11. [Memory-System](#memory-system)
+12. [Skill-System](#skill-system)
+13. [Telegram-Integration](#telegram-integration)
+14. [Cronjob-System](#cronjob-system)
+15. [Krea-Bildgenerierung](#krea-bildgenerierung)
+16. [Auth & Multi-User](#auth--multi-user)
+17. [Workspace & File-Explorer](#workspace--file-explorer)
+18. [Windows Desktop App](#windows-desktop-app)
+19. [Deployment](#deployment)
+20. [Konfiguration](#konfiguration)
+21. [Datenbank-Migrationen](#datenbank-migrationen)
+
+---
+
+## Überblick
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Browser / WebView2                     │
+│              Vanilla JS SPA (wwwroot/)                      │
+├─────────────────────────────────────────────────────────────┤
+│                   ASP.NET 10 Minimal API                    │
+│              http://0.0.0.0:19000                           │
+├──────┬──────┬──────┬──────┬──────┬──────┬──────┬───────────┤
+│ Auth │ Chat │ Hist │ Sess │Agent │ Tele │ Cron │  Krea     │
+│      │  SSE │      │      │      │ gram │ jobs │  Images   │
+├──────┴──────┴──────┴──────┴──────┴──────┴──────┴───────────┤
+│              Services Layer                                 │
+│  AnthropicService · ChatService · ToolService               │
+│  DatabaseService · MemoryService · SkillService             │
+│  TelegramService · CronjobService · KreaService             │
+├─────────────────────────────────────────────────────────────┤
+│              SQLite (data/gott.db) via Dapper               │
+│              Filesystem (data/agents/, data/skills/)        │
+├─────────────────────────────────────────────────────────────┤
+│              Anthropic Claude API (claude-sonnet/opus/haiku) │
+│              Krea API (Bildgenerierung)                     │
+│              Telegram Bot API                               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Tech-Stack
+
+| Schicht       | Technologie                                               |
+|---------------|-----------------------------------------------------------|
+| **Runtime**   | .NET 10 (ohne Nullable, ohne Implicit Usings)             |
+| **Web**       | ASP.NET Minimal API, Kestrel                              |
+| **Datenbank** | SQLite via Microsoft.Data.Sqlite + Dapper                 |
+| **AI**        | Anthropic Claude API (Streaming SSE + Non-Streaming)      |
+| **Images**    | SixLabors.ImageSharp (Resize, Thumbnails)                 |
+| **Cron**      | Cronos (Cron-Expression-Parsing)                          |
+| **Frontend**  | Vanilla JavaScript SPA (kein Framework)                   |
+| **Markdown**  | marked.js (Client-side Rendering)                         |
+| **Editor**    | CodeMirror 5 + EasyMDE                                    |
+| **Icons**     | Font Awesome                                              |
+| **Fonts**     | Inter, JetBrains Mono (self-hosted)                       |
+| **Desktop**   | WPF + WebView2 (.NET 10, Windows-only)                    |
+
+---
+
+## Projektstruktur
+
+```
+gott/
+├── Program.cs                    # Startup, DI, Middleware, Routing
+├── gott.csproj                   # Projekt-Definition (.NET 10)
+├── appsettings.json              # Konfiguration (Tokens, Limits)
+├── deploy.sh                     # Deployment-Script (systemctl)
+│
+├── Models/                       # Daten-Modelle (Records)
+│   ├── UserRecord.cs
+│   ├── AgentRecord.cs
+│   ├── SessionRecord.cs
+│   ├── ChainRecord.cs
+│   ├── MessageRecord.cs          # + AttachmentRecord
+│   ├── ArchiveRecord.cs
+│   ├── CronjobRecord.cs
+│   ├── KreaImageRecord.cs
+│   ├── ChatModels.cs             # ChatMessage, ChatRequest, AttachmentInfo/Block
+│   └── ChatContext.cs            # Runtime-Kontext für einen Chat
+│
+├── Services/                     # Business-Logic
+│   ├── DatabaseService.cs        # SQLite CRUD, Schema, Migrationen
+│   ├── AuthService.cs            # Token-basierte Authentifizierung
+│   ├── ChatService.cs            # Kontext-Aufbau, History-Builder
+│   ├── AnthropicService.cs       # Claude API (Streaming + Non-Streaming)
+│   ├── ToolService.cs            # Tool-Definitionen + Ausführung
+│   ├── SystemPromptBuilder.cs    # Modularer System-Prompt aus Blöcken
+│   ├── MemoryService.cs          # Agent-Gedächtnis (Dateisystem)
+│   ├── SkillService.cs           # Skill-Verwaltung (Dateisystem)
+│   ├── TelegramService.cs        # Telegram Bot API Integration
+│   ├── CronjobService.cs         # BackgroundService für Cron-Tasks
+│   ├── KreaService.cs            # Krea Image Generation API
+│   ├── ImageService.cs           # Bild-Resize (Avatar, Session-Image)
+│   └── StreamingTracker.cs       # Concurrent Tracking aktiver Streams
+│
+├── Endpoints/                    # HTTP API (Minimal API)
+│   ├── AuthEndpoint.cs           # Login, Logout, Me
+│   ├── ChatEndpoint.cs           # POST /api/chat (SSE Streaming)
+│   ├── HistoryEndpoint.cs        # History, Archive, Attachments, Marks
+│   ├── SessionEndpoint.cs        # CRUD + SystemPrompt, Exec, Git-Status
+│   ├── AgentEndpoint.cs          # CRUD
+│   ├── WorkspaceEndpoint.cs      # File-Tree, File-Read/Write, Browse, Agent-Files
+│   ├── TelegramEndpoint.cs       # Webhook, Config, Registration
+│   ├── CronjobEndpoint.cs        # CRUD + Toggle, Manual Run
+│   ├── KreaEndpoint.cs           # Generate, List, File-Serve
+│   ├── SkillEndpoint.cs          # List, Agent-Skill-Mapping, Output-Files
+│   ├── ProfileEndpoint.cs        # Profil, Persona, Passwort
+│   ├── SettingsEndpoint.cs       # User-Settings (JSON blob)
+│   ├── BackupEndpoint.cs         # Backup als tar.gz Download
+│   └── InfoEndpoint.cs           # Build-Zeitstempel
+│
+├── Middleware/
+│   └── AuthMiddleware.cs         # Cookie-basierte Token-Validierung
+│
+├── Extensions/
+│   └── HttpContextExtensions.cs  # GetUserId(), IsAdmin()
+│
+├── Templates/                    # Standard-Templates für neue Agents
+│   ├── IDENTITY.md               # Wer bin ich? (Name, Sprache)
+│   ├── SOUL.md                   # Persönlichkeit, Verhalten
+│   └── USER.md                   # Infos über den User
+│
+├── wwwroot/                      # Frontend (Vanilla JS SPA)
+│   ├── index.html                # Single HTML Entry Point
+│   ├── css/                      # Stylesheets
+│   │   ├── theme.css             # CSS Custom Properties (Dark Theme)
+│   │   ├── base.css              # Reset, Grundlayout
+│   │   ├── main.css              # Sidebar, Layout-Struktur
+│   │   ├── chat.css              # Chat-Nachrichten, Bubbles
+│   │   ├── dashboard.css         # Dashboard-Grid
+│   │   ├── form.css              # Formulare, Inputs
+│   │   ├── markdown.css          # Markdown-Rendering-Styles
+│   │   ├── file-explorer.css     # File-Explorer Panel
+│   │   ├── login.css             # Login-Seite
+│   │   ├── mobile.css            # Responsive Anpassungen
+│   │   ├── tooltip.css           # Tooltip-Styles
+│   │   ├── fonts.css             # @font-face Definitionen
+│   │   ├── placeholder.css       # Placeholder/Loading States
+│   │   ├── codemirror.min.css    # CodeMirror Editor
+│   │   └── easymde.min.css       # EasyMDE Editor
+│   ├── js/
+│   │   ├── app.js                # App-Initialisierung, Auth-Check
+│   │   ├── router.js             # Client-side SPA Router
+│   │   ├── api.js                # API-Client (fetch wrapper)
+│   │   ├── ui.js                 # UI-Utilities (Modal, Toast, etc.)
+│   │   ├── chat.js               # Chat-Logic, SSE-Streaming
+│   │   ├── history.js            # History-Rendering, Pagination
+│   │   ├── session.js            # Session-Verwaltung
+│   │   ├── file-explorer.js      # File-Explorer Komponente
+│   │   ├── commands-ui.js        # Custom-Commands UI
+│   │   ├── emoji.js              # Emoji-Picker
+│   │   ├── emoji.userdata.js     # Häufig genutzte Emojis
+│   │   ├── tooltip.js            # Tooltip-System
+│   │   ├── title.js              # Tab-Titel-Management
+│   │   ├── pages/                # Seiten-Komponenten
+│   │   │   ├── chat-page.js      # Haupt-Chat-Ansicht
+│   │   │   ├── dashboard.js      # Dashboard / Home
+│   │   │   ├── session-page.js   # Session-Einstellungen
+│   │   │   ├── agent-page.js     # Agent-Editor
+│   │   │   ├── cronjob-page.js   # Cronjob-Verwaltung
+│   │   │   ├── profile-page.js   # Profil-Bearbeitung
+│   │   │   ├── settings-page.js  # App-Einstellungen
+│   │   │   └── login-page.js     # Login-Formular
+│   │   └── lib/                  # Vendor-Libraries
+│   │       ├── marked.min.js     # Markdown Parser
+│   │       ├── codemirror.min.js # Code Editor
+│   │       ├── codemirror.cjs    # CM CommonJS Wrapper
+│   │       ├── easymde.min.js    # Markdown Editor
+│   │       └── cm-mode-*.min.js  # CodeMirror Syntax-Modes
+│   ├── fonts/                    # Self-hosted Fonts (Inter, JetBrains Mono)
+│   └── lib/font-awesome/         # Font Awesome Icons
+│
+├── WindowsApp/                   # Windows Desktop Client (WPF)
+│   ├── Gott.csproj               # .NET 10 Windows, WebView2
+│   ├── App.xaml / App.xaml.cs     # WPF Application
+│   ├── MainWindow.xaml/cs        # WebView2 Host Window
+│   └── appsettings.json          # Server-URL Konfiguration
+│
+└── publish/                      # Build-Output (NICHT editieren!)
+    └── data/
+        ├── gott.db               # SQLite Datenbank
+        ├── agents/               # Agent Memory-Dateien
+        │   └── {agentId}/
+        │       ├── IDENTITY.md
+        │       ├── SOUL.md
+        │       ├── MEMORY.md
+        │       └── memory/       # Tages-Logs etc.
+        ├── skills/               # Skill-Verzeichnisse
+        │   └── {slug}/
+        │       ├── SKILL.md
+        │       ├── PROMPT.md
+        │       └── output/
+        ├── images/               # Krea-generierte Bilder
+        ├── logs/                 # Payload-Logs (optional)
+        └── backup/               # Backup-Archive
+```
+
+---
+
+## Datenmodell
+
+### Entity-Relationship
+
+```
+User (1) ─── (*) Agent
+User (1) ─── (*) Session
+Agent (1) ─── (*) Session     (Session hat optional einen Agent)
+Agent (*) ─── (*) Skill       (via agent_skills Tabelle)
+Session (1) ─── (*) Chain     (ein Chat-Request = eine Chain)
+Session (1) ─── (*) Archive   (archivierte Chains)
+Chain (1) ─── (*) Message
+Message (1) ─── (*) Attachment
+Session (1) ─── (*) Cronjob
+User (1) ─── (*) Cronjob
+```
+
+### Tabellen
+
+| Tabelle           | Beschreibung                                        |
+|-------------------|-----------------------------------------------------|
+| `users`           | Benutzer (username, password_hash, persona, settings) |
+| `tokens`          | Auth-Tokens (token → user_id)                       |
+| `agents`          | AI-Agenten (model, soul, identity, memory, tools)   |
+| `sessions`        | Chat-Sessions (workspace, context, telegram-config) |
+| `chains`          | Request-Chains (model, tokens, iterations, timing)  |
+| `messages`        | Einzelne Nachrichten (text, tool_use, tool_result)   |
+| `attachments`     | Datei-Anhänge (base64, image/document)              |
+| `archives`        | Archivierte Chain-Gruppen                           |
+| `agent_skills`    | Agent ↔ Skill Zuordnung                             |
+| `cronjobs`        | Geplante Tasks (cron expression, prompt)            |
+| `telegram_links`  | Telegram Chat ↔ Session Verknüpfung                |
+
+### Zentrale Records
+
+**ChainRecord** – Repräsentiert einen kompletten Request-Response-Zyklus:
+- `ChainId` – Eindeutige ID
+- `SessionId` – Zugehörige Session
+- `Model` – Verwendetes Claude-Modell (z.B. `claude-sonnet-4-6`)
+- `SystemPrompt` – Der vollständige System-Prompt (gespeichert für Nachvollziehbarkeit)
+- `InputTokens`, `OutputTokens`, `CacheCreationTokens`, `CacheReadTokens` – Token-Verbrauch
+- `Iterations` – Anzahl der Tool-Loop-Durchläufe
+- `StopReason` – `end_turn`, `tool_use`, `max_iterations`, `error`, `client_disconnected`
+- `DurationMs` – Gesamtdauer der Chain
+
+**MessageRecord** – Eine einzelne Nachricht innerhalb einer Chain:
+- `Role` – `user`, `assistant`, `system`
+- `Type` – `text`, `tool_use`, `tool_result`, `error`
+- `Content` – Textinhalt oder JSON (bei tool_use: Input-JSON)
+- `ToolName`, `ToolCallId` – Bei Tool-Aufrufen
+- `IsMarked` – Als wichtig markierte Nachricht (wird in System-Prompt aufgenommen)
+- `DeletedOn` – Soft-Delete Zeitstempel
+
+---
+
+## Backend-Architektur
+
+### Program.cs – Startup
+
+Die `Program.cs` ist der zentrale Einstiegspunkt und konfiguriert:
+
+1. **Service-Registrierung** – Alle Services als Singletons im DI-Container
+2. **Datenbank-Initialisierung** – `DatabaseService` erstellt Schema + Migrationen
+3. **Default-User** – Wird automatisch angelegt falls keine User existieren
+4. **Middleware** – Static Files → `AuthMiddleware` → Endpoints
+5. **Endpoint-Mapping** – Alle 14 Endpoint-Gruppen registriert
+6. **Server** – Kestrel auf `http://0.0.0.0:19000`
+
+Initialisierungsreihenfolge:
+```
+AuthService → DatabaseService → EnsureDefaultUser
+→ ImageService, StreamingTracker, MemoryService, SkillService
+→ ToolService → ChatService
+→ AnthropicService → TelegramService → KreaService
+→ CronjobService (BackgroundService)
+```
+
+### Services
+
+| Service                | Typ          | Aufgabe                                                          |
+|------------------------|--------------|------------------------------------------------------------------|
+| `DatabaseService`      | Singleton    | SQLite CRUD, Schema-Init, Migrationen, alle DB-Operationen       |
+| `AuthService`          | Singleton    | Token-Erzeugung/-Validierung, Passwort-Hashing (SHA256)         |
+| `ChatService`          | Singleton    | Chat-Kontext aufbauen, History aus DB rekonstruieren             |
+| `AnthropicService`     | Singleton    | Claude API Kommunikation (Streaming SSE + Non-Streaming)         |
+| `ToolService`          | Singleton    | Tool-Definitionen bereitstellen, Tool-Aufrufe ausführen          |
+| `SystemPromptBuilder`  | Static       | Modularer System-Prompt aus konfigurierbaren Blöcken             |
+| `MemoryService`        | Singleton    | Agent-Gedächtnis auf Dateisystem (MEMORY.md, IDENTITY.md etc.)   |
+| `SkillService`         | Singleton    | Skill-Discovery und -Management aus Dateisystem                  |
+| `TelegramService`      | Singleton    | Telegram Bot API, Webhook-Handling, Nachrichten senden           |
+| `CronjobService`       | Background   | Minütlicher Check auf fällige Cronjobs, Ausführung via Claude    |
+| `KreaService`          | Singleton    | Krea API für Bildgenerierung, Job-Polling, Image-Download        |
+| `ImageService`         | Singleton    | Bild-Resize (max 512px) für Avatare und Session-Bilder           |
+| `StreamingTracker`     | Singleton    | ConcurrentDictionary – trackt welche Sessions gerade streamen    |
+
+### Endpoints (API)
+
+Alle Endpoints folgen dem **Minimal API**-Pattern mit Extension Methods (`MapXxxEndpoints`).
+
+| Gruppe        | Basis-Route                | Methoden                                    |
+|---------------|----------------------------|---------------------------------------------|
+| **Auth**      | `/api/auth/`               | `POST login`, `POST logout`, `GET me`       |
+| **Chat**      | `/api/chat`                | `POST` (SSE Streaming)                      |
+| **History**   | `/api/history`             | `GET history`, `GET poll`, `POST archive`, `GET archives`, `GET archive/{id}`, `GET attachments/{id}`, `PUT messages/{id}/mark`, `PUT messages/{id}/delete`, `GET chains/{id}` |
+| **Sessions**  | `/api/sessions/`           | CRUD + `GET system-prompt`, `GET system-prompt-blocks`, `GET streaming`, `POST exec`, `GET git-status` |
+| **Agents**    | `/api/agents/`             | CRUD                                        |
+| **Workspace** | `/api/workspace/`          | `GET tree`, `GET/PUT file`, `GET browse`, `GET agent/tree`, `GET/PUT agent/file`, `GET raw` |
+| **Telegram**  | `/api/telegram/`           | `POST webhook/{sessionId}` (unauthenticated), Session-Config CRUD, Webhook-Management |
+| **Cronjobs**  | `/api/cronjobs/`           | CRUD + `POST toggle`, `POST run`            |
+| **Krea**      | `/api/images/`             | `POST generate`, `GET list`, `GET file/{name}`, `GET status` |
+| **Skills**    | `/api/skills`              | `GET list`, `GET/PUT agent skills`, Output-Files + Thumbnails |
+| **Profile**   | `/api/profile`             | `GET`, `PUT`, `PUT password`                |
+| **Settings**  | `/api/settings`            | `GET`, `PUT`                                |
+| **Backup**    | `/api/backup`              | `POST` (Admin only, tar.gz Download)        |
+| **Info**      | `/api/info`                | `GET` (Build-Zeitstempel)                   |
+
+### Middleware
+
+**AuthMiddleware** prüft jede `/api/`-Anfrage auf ein gültiges `gott_token`-Cookie.
+
+Ausnahmen (kein Auth nötig):
+- Statische Dateien (nicht `/api/`)
+- `POST /api/auth/login`
+- `POST /api/telegram/webhook/{sessionId}` (authentifiziert via Secret-Header)
+
+Bei Erfolg werden `UserId` und `IsAdmin` in `HttpContext.Items` gesetzt.
+
+### Models
+
+Die Models in `Models/` sind reine Daten-Records ohne Business-Logic (Ausnahme: `ChatMessage` hat Helper-Methoden für Content-Extraktion und `UserRecord` hat `GetEffectivePersona()`).
+
+**ChatContext** ist ein Runtime-Objekt das den vollständigen Kontext eines Chat-Requests hält:
+- Chain-ID, Session-ID, Model-ID
+- Aufgelöster System-Prompt (Text + strukturierte Blöcke)
+- Workspace-Pfad, Tool-Choice
+- Referenzen auf Agent und Session Records
+
+### Templates
+
+`Templates/` enthält Vorlagen die beim Erstellen eines neuen Agents in dessen Memory-Verzeichnis kopiert werden:
+
+- **IDENTITY.md** – Name und Grundinfos (Platzhalter `{NAME}` wird ersetzt)
+- **SOUL.md** – Persönlichkeit und Verhaltensgrundsätze
+- **USER.md** – Informationen über den User (global, nicht agent-spezifisch)
+
+---
+
+## Frontend-Architektur
+
+Das Frontend ist eine **Single-Page Application** ohne Build-Step, komplett in Vanilla JavaScript.
+
+### Routing
+
+`router.js` implementiert ein Hash-basiertes Client-Side-Routing:
+
+| Route                    | Page                | Beschreibung              |
+|--------------------------|---------------------|---------------------------|
+| `#/`                     | `dashboard.js`      | Session-Übersicht         |
+| `#/chat/{sessionId}`     | `chat-page.js`      | Chat-Ansicht              |
+| `#/session/{sessionId}`  | `session-page.js`   | Session-Einstellungen     |
+| `#/agent/{agentId}`      | `agent-page.js`     | Agent-Editor              |
+| `#/cronjobs`             | `cronjob-page.js`   | Cronjob-Verwaltung        |
+| `#/profile`              | `profile-page.js`   | Profil                    |
+| `#/settings`             | `settings-page.js`  | App-Einstellungen         |
+| `#/login`                | `login-page.js`     | Login                     |
+
+### Kern-Module
+
+- **app.js** – Initialisierung, Auth-Check, globale Event-Handler
+- **api.js** – Zentraler API-Client mit `fetch()`-Wrapper, Auth-Redirect bei 401
+- **ui.js** – UI-Utilities (Modals, Toasts, Confirmations, etc.)
+- **chat.js** – SSE-Stream-Handling, Markdown-Rendering, Tool-Output-Darstellung
+- **history.js** – Chat-History laden, paginieren, rendern
+- **session.js** – Session-State-Management
+- **file-explorer.js** – Workspace File-Explorer Panel
+- **commands-ui.js** – Custom-Commands UI-Komponente
+- **emoji.js** – Emoji-Picker mit Kategorien und Suche
+- **tooltip.js** – Tooltip-System für Hover-Infos
+- **title.js** – Dynamisches Tab-Titel-Management
+
+### Styling
+
+CSS ist in modulare Dateien aufgeteilt mit CSS Custom Properties für Theming:
+
+- `theme.css` – Alle Farben, Abstände, Schriften als CSS Variables
+- `base.css` – Reset und Grundlayout
+- `main.css` – Sidebar, Content-Area, Responsive Layout
+- `chat.css` – Chat-Bubbles, Streaming-Animation, Tool-Outputs
+- `markdown.css` – Rendering von Markdown in Nachrichten
+- `mobile.css` – Responsive Breakpoints und Anpassungen
+
+---
+
+## Chat-Pipeline
+
+Der Chat-Flow von User-Input bis zur gerenderten Antwort:
+
+```
+1. User tippt Nachricht + optionale Attachments (Bilder/Dokumente)
+   ↓
+2. Frontend: POST /api/chat { content, sessionId }
+   ↓
+3. ChatEndpoint:
+   a) User-Message + Attachments in DB speichern
+   b) ChatService.PrepareContext() → Agent, Model, System-Prompt, Chain
+   c) ChatService.BuildHistoryFromDb() → vollständige Message-History
+   d) AnthropicService.StreamChat() starten
+   ↓
+4. AnthropicService (Agentic Loop):
+   ┌─────────────────────────────────────────┐
+   │  while (iterations < maxIterations)      │
+   │    → Claude API Request (SSE)            │
+   │    → Stream-Processing:                  │
+   │      • Text-Tokens → SSE an Frontend     │
+   │      • Tool-Use → ToolService.Execute()  │
+   │      • Tool-Results → nächste Iteration  │
+   │    → Messages in DB persistieren         │
+   │    → Stop wenn: end_turn / max_iterations│
+   └─────────────────────────────────────────┘
+   ↓
+5. Frontend: SSE Events empfangen und rendern
+   • "text" → Markdown parsen, Token für Token anzeigen
+   • "tool_*" → Tool-Aufrufe collapsible darstellen
+   • "done" → Token-Stats, Dauer, Model anzeigen
+```
+
+### Streaming vs Non-Streaming
+
+- **Web-Chat**: Streaming via SSE (`text/event-stream`). Tokens werden in Echtzeit gerendert.
+- **Telegram**: Non-Streaming via `ChatNonStreaming()`. Vollständige Antwort wird abgewartet und als Telegram-Nachricht gesendet.
+- **Cronjobs**: Non-Streaming, wie Telegram.
+
+### History-Optimierung
+
+Die History-Rekonstruktion in `BuildHistoryFromDb()` ist optimiert:
+
+- **Ältere Chains**: Nur `text`-Messages (user + assistant), keine Tool-Calls
+- **Letzte Chain**: Vollständig mit allen Tool-Use/Tool-Result Blöcken
+- **Attachments**: Nur für die letzte User-Message geladen (spart enorme Token)
+- **Tool-Results**: In der History auf 20.000 Zeichen gekürzt (vollständig in DB)
+
+---
+
+## Tool-System
+
+Der Agent hat Zugriff auf folgende Tools, abhängig von Konfiguration:
+
+### Datei-Tools (wenn Workspace konfiguriert)
+
+| Tool          | Beschreibung                                    |
+|---------------|--------------------------------------------------|
+| `read_file`   | Datei lesen (relativer Pfad zum Workspace)       |
+| `write_file`  | Datei erstellen/überschreiben                    |
+| `edit_file`   | Exakten Textabschnitt in Datei ersetzen          |
+| `list_files`  | Verzeichnis-Listing                              |
+| `delete_file` | Datei oder leeres Verzeichnis löschen            |
+| `execute`     | Shell-Befehl ausführen (bash, 180s Timeout)      |
+| `glob`        | Dateien via Glob-Pattern finden                  |
+| `grep`        | Dateien nach Regex/Text durchsuchen              |
+| `todo_write`  | Todo-Liste schreiben (als Datei im Workspace)    |
+
+### Memory-Tools (wenn UseMemory aktiviert)
+
+| Tool           | Beschreibung                              |
+|----------------|-------------------------------------------|
+| `memory_read`  | Memory-Datei des Agents lesen             |
+| `memory_write` | Memory-Datei schreiben (überschreiben/append) |
+| `memory_list`  | Alle Memory-Dateien des Agents auflisten  |
+
+### Web-Suche (wenn WebSearchVersion konfiguriert)
+
+Nutzt Anthropics eingebaute Web-Suche als Server-Side-Tool.
+
+### Tool-Choice Strategien
+
+- **`any`**: Erste Iteration erzwingt Tool-Nutzung, danach `auto`. Verhindert dass der Agent nur Text antwortet wenn Tools benötigt werden.
+- **`auto`**: Claude entscheidet frei ob Tools nötig sind.
+
+### Pfad-Sicherheit
+
+Alle Dateipfade werden via `ResolvePath()` aufgelöst und gegen den Workspace/Memory-Ordner geprüft – Path-Traversal-Angriffe werden verhindert.
+
+---
+
+## Agent-System
+
+Ein **Agent** definiert die Persönlichkeit und Fähigkeiten der AI:
+
+| Eigenschaft       | Beschreibung                                                     |
+|-------------------|------------------------------------------------------------------|
+| `Name`            | Anzeigename                                                     |
+| `Avatar`          | Base64 Data-URL (auf 512px resized)                              |
+| `Model`           | `sonnet`, `sonnet-4-5`, `sonnet-4-6`, `opus`, `opus-4-5`, `opus-4-6`, `haiku`, `haiku-4-5` |
+| `ToolChoice`      | `any` oder `auto`                                                |
+| `CustomCommands`  | JSON-Array mit Slash-Commands (Label + Prompt)                   |
+| `AutoCommit`      | `""` (nichts), `"mention"` (verbieten), `"enforce"` (erzwingen), `"forbid"` (strikt verboten) |
+| `UseSoul`         | SOUL.md in System-Prompt einbinden                               |
+| `UseIdentity`     | IDENTITY.md in System-Prompt einbinden                           |
+| `UseUserInfo`     | User-Persona in System-Prompt einbinden                          |
+| `UseMemory`       | Memory-Tools aktivieren                                          |
+| `WebSearchVersion`| Web-Suche aktivieren (z.B. `web_search_20260209`)                |
+
+### Model-Auflösung
+
+```
+"sonnet"     → claude-sonnet-4-6
+"sonnet-4-5" → claude-sonnet-4-5
+"opus"       → claude-opus-4-6
+"haiku"      → claude-haiku-4-5
+```
+
+---
+
+## System-Prompt-Aufbau
+
+Der `SystemPromptBuilder` erzeugt den System-Prompt modular aus konfigurierbaren **Blöcken**:
+
+```
+┌──────────────────────────────────────────┐
+│ 1. IDENTITY.md (UseIdentity)             │  → Wer ist der Agent?
+│ 2. SOUL.md (UseSoul)                     │  → Persönlichkeit, Verhalten
+│ 3. User-Persona (UseUserInfo)            │  → Infos über den User
+│ 4. Tool-Nutzung (Workspace + any)        │  → "IMMER Tools benutzen"
+│ 5. Workspace-Info                        │  → Tools + Workspace-Pfad
+│ 6. Session-Kontext                       │  → Freiformtext
+│ 7. Skills (Agent-Skills)                 │  → Skill-Prompts
+│ 8. Memory (UseMemory)                    │  → Memory-Regeln + MEMORY.md Inhalt
+│ 9. Git-Verhalten (AutoCommit)            │  → Commit-Regeln
+│10. Verhaltensregeln (Workspace + any)    │  → "IMMER Tools aufrufen"
+│11. Erinnerung (Workspace + any)          │  → Höchste Priorität: Tool-Aufrufe!
+│12. Markierte Nachrichten                 │  → Vom User als wichtig markierte Messages
+└──────────────────────────────────────────┘
+```
+
+Jeder Block hat:
+- **Icon** – Font Awesome Icon-Klasse
+- **Label** – Beschreibender Titel
+- **Content** – Markdown-Text
+
+Die Blöcke sind über die API als JSON abrufbar (`GET /api/sessions/{id}/system-prompt-blocks`), sodass das Frontend sie einzeln inspizierbar darstellen kann.
+
+---
+
+## Memory-System
+
+Jeder Agent hat ein eigenes **Dateisystem-basiertes Gedächtnis**:
+
+```
+data/agents/{agentId}/
+├── IDENTITY.md      # Identität (aus Template initialisiert)
+├── SOUL.md          # Persönlichkeit (aus Template initialisiert)
+├── MEMORY.md        # Haupt-Memory (kuratierte Informationen)
+└── memory/          # Unterordner für Tages-Logs, Themen
+    ├── 2025-07-13.md
+    └── ...
+```
+
+### Funktionsweise
+
+1. **Initialisierung**: Beim Erstellen eines Agents werden `IDENTITY.md` und `SOUL.md` aus `Templates/` kopiert
+2. **Lesen**: Der Agent kann seine Memory-Dateien via `memory_read` Tool lesen
+3. **Schreiben**: Via `memory_write` (überschreiben oder append)
+4. **Auflisten**: Via `memory_list` alle Dateien durchsuchen
+5. **System-Prompt**: `MEMORY.md` Inhalt wird automatisch in den System-Prompt eingebettet
+6. **IDENTITY.md** und **SOUL.md**: Werden als eigene System-Prompt-Blöcke eingebunden (wenn aktiviert)
+
+### Sandbox
+
+Alle Pfade werden gegen das Agent-Verzeichnis geprüft – kein Zugriff außerhalb möglich.
+
+---
+
+## Skill-System
+
+Skills sind **Dateisystem-basierte Erweiterungen** die einem Agent zugeordnet werden können:
+
+```
+data/skills/{slug}/
+├── SKILL.md          # Metadaten (Name, Description, Version im Frontmatter)
+├── PROMPT.md         # System-Prompt-Erweiterung (in Agent-Prompt eingebettet)
+├── _meta.json        # Alternative Metadaten (Fallback)
+└── output/           # Skill-Output (Bilder, Dateien, etc.)
+```
+
+### SKILL.md Frontmatter
+
+```yaml
+---
+name: Mein Skill
+description: Beschreibung
+version: 1.0
+---
+```
+
+### Agent-Zuordnung
+
+Skills werden über die `agent_skills` Tabelle einem Agent zugeordnet. Der `PROMPT.md`-Inhalt aller zugeordneten Skills wird als ein System-Prompt-Block eingefügt.
+
+### Workspace-Implikation
+
+Wenn ein Agent Skills hat aber kein Workspace konfiguriert ist, wird automatisch `/tmp` als Workspace gesetzt (damit `execute` für Skill-Commands funktioniert).
+
+---
+
+## Telegram-Integration
+
+Sessions können mit einem **Telegram Bot** verbunden werden:
+
+### Konfiguration
+
+Pro Session werden gespeichert:
+- `TelegramBotToken` – Bot-Token von @BotFather
+- `TelegramWebhookSecret` – Geheimer Token für Webhook-Verifizierung
+- `TelegramChatId` – Verknüpfte Chat-ID
+
+### Webhook-Flow
+
+```
+1. User konfiguriert Bot-Token in Session-Settings
+2. User registriert Webhook (POST .../telegram/register-webhook)
+   → Setzt Webhook-URL: {baseUrl}/api/telegram/webhook/{sessionId}
+3. Telegram sendet Updates an Webhook
+4. AuthMiddleware lässt Webhook-Requests durch (kein Cookie nötig)
+5. TelegramEndpoint prüft X-Telegram-Bot-Api-Secret-Token Header
+6. TelegramService verarbeitet Update:
+   - /start → Session verknüpfen
+   - /clear → History archivieren
+   - /status → Session-Info anzeigen
+   - /unlink → Verknüpfung aufheben
+   - Text → An Claude weiterleiten (Non-Streaming)
+```
+
+### Non-Streaming Chat
+
+Telegram-Nachrichten werden über `AnthropicService.ChatNonStreaming()` verarbeitet. Die History wird genauso aus der DB aufgebaut wie beim Web-Chat. Antworten über 4096 Zeichen werden automatisch in Chunks aufgeteilt.
+
+---
+
+## Cronjob-System
+
+Der `CronjobService` ist ein **BackgroundService** der minütlich nach fälligen Jobs prüft.
+
+### Datenmodell
+
+| Feld               | Beschreibung                                    |
+|---------------------|------------------------------------------------|
+| `CronExpression`   | Standard-Cron-Format (5 Felder), via Cronos    |
+| `SessionId`        | Session in der der Job läuft                    |
+| `Prompt`           | Text der als User-Message an Claude gesendet wird |
+| `NotifySessionId`  | Optionale Session für Benachrichtigung          |
+| `IsEnabled`        | Aktiviert/Deaktiviert                           |
+| `NextRunAt`        | Nächste geplante Ausführung (UTC)               |
+
+### Ausführungsflow
+
+```
+1. CronjobService prüft jede Minute
+2. Fällige Jobs (next_run_at <= jetzt) werden geladen
+3. Für jeden Job:
+   a) ChatService.PrepareContext() – Chain + System-Prompt aufbauen
+   b) History aus DB laden
+   c) Prompt als User-Message anhängen + in DB speichern
+   d) AnthropicService.ChatNonStreaming() ausführen
+   e) Telegram-Benachrichtigung senden (auf Arbeits-Session)
+   f) Optional: Zusammenfassung in Notify-Session schreiben + Telegram dort
+   g) Nächste Ausführung berechnen + DB aktualisieren
+```
+
+### Benachrichtigungen
+
+- **Arbeits-Session**: Wenn die Session Telegram hat, wird die Antwort dort gepostet
+- **Notify-Session**: Wenn konfiguriert, wird eine Zusammenfassung in eine andere Session geschrieben und der Agent dort antwortet darauf
+
+---
+
+## Krea-Bildgenerierung
+
+Die `KreaService` ermöglicht Bildgenerierung über die Krea API.
+
+### Unterstützte Modelle
+
+```
+flux, flux-kontext, flux-1.1-pro, flux-1.1-pro-ultra,
+nano-banana, nano-banana-pro, imagen-3, imagen-4, imagen-4-fast, imagen-4-ultra,
+ideogram-2-turbo, ideogram-3, seedream-3, seedream-4,
+chatgpt-image, runway-gen-4
+```
+
+### Flow
+
+```
+1. POST /api/images/generate { prompt, model, width, height, ... }
+2. KreaService sendet Request an Krea API
+3. Job-Polling bis Status "completed"
+4. Bilder herunterladen nach data/images/
+5. Metadaten als JSON speichern
+6. Response mit Dateinamen + URLs
+```
+
+### Bild-Serving
+
+- `GET /api/images` – Liste aller generierten Bilder (aus Metadaten-JSON)
+- `GET /api/images/file/{filename}` – Einzelnes Bild ausliefern
+
+---
+
+## Auth & Multi-User
+
+### Authentifizierung
+
+- **Login**: Username + Passwort → SHA256 Hash-Vergleich → Token generieren
+- **Token**: 32 Bytes Random, als `gott_token` HttpOnly Cookie (365 Tage)
+- **Validierung**: Jeder API-Call prüft Token → User-ID
+- **Logout**: Token aus DB löschen + Cookie entfernen
+
+### Multi-User-Isolation
+
+- Sessions sind an `user_id` gebunden
+- Agents sind an `user_id` gebunden
+- Cronjobs sind an `user_id` gebunden
+- Jeder User sieht nur seine eigenen Daten
+- Admin-Flag (`is_admin`) für Backup-Endpoint
+
+### Default-User
+
+Beim ersten Start wird automatisch ein Default-User erstellt (`DatabaseService.EnsureDefaultUser()`).
+
+### User-Persona
+
+Jeder User hat eine optionale **Persona** – ein Freitext der beschreibt wer er ist. Diese wird (wenn `UseUserInfo` am Agent aktiv ist) in den System-Prompt als "Dein Gegenüber" eingebettet.
+
+---
+
+## Workspace & File-Explorer
+
+### Workspace
+
+Eine Session kann einen **Workspace-Pfad** haben (z.B. `/app/gott`). Dieser:
+- Aktiviert die Datei-/Shell-Tools für den Agent
+- Ermöglicht den File-Explorer im Frontend
+- Bietet `git status` Informationen
+- Erlaubt das Ausführen von Shell-Befehlen (foreground + background)
+
+### File-Explorer API
+
+| Endpoint                          | Beschreibung                           |
+|-----------------------------------|----------------------------------------|
+| `GET /api/workspace/tree`         | Verzeichnisbaum (mit Ignore-Filtern)  |
+| `GET /api/workspace/file`         | Dateiinhalt lesen (max 2MB)           |
+| `PUT /api/workspace/file`         | Datei speichern                       |
+| `GET /api/workspace/browse`       | Verzeichnis-Browser (für Pfad-Auswahl)|
+| `GET /api/workspace/raw`          | Raw-Datei ausliefern (Bilder, PDFs)   |
+| `GET /api/workspace/agent/tree`   | Agent-Memory-Verzeichnis              |
+| `GET/PUT /api/workspace/agent/file` | Agent-Memory-Dateien lesen/schreiben |
+
+### Ignored Directories
+
+`bin`, `obj`, `node_modules`, `.git`, `.vs`, `.idea`, `publish`, `dist`, `out`, `build`, `target`, `.cache`
+
+### Session-Exec
+
+`POST /api/sessions/{id}/exec` führt Shell-Befehle im Workspace aus:
+- **foreground**: Synchron, wartet auf Ergebnis (30s Timeout)
+- **background**: Fire-and-forget via `systemd-run`
+
+---
+
+## Windows Desktop App
+
+Im `WindowsApp/`-Ordner liegt ein minimaler **WPF WebView2 Client**:
+
+- .NET 10 Windows, `Microsoft.Web.WebView2`
+- Lädt die Web-UI in einem nativen Fenster
+- Server-URL konfigurierbar via `appsettings.json`
+- Dark Background um weißen Flash zu vermeiden
+- Externe Links öffnen im Standard-Browser
+- Fenster: 930px breit, 95% Bildschirmhöhe, zentriert
+
+---
+
+## Deployment
+
+### deploy.sh
+
+```bash
+#!/bin/bash
+set -e
+cd /app/gott
+export PATH="$HOME/.dotnet:$PATH"
+systemctl stop gott
+dotnet publish -c Release -o publish
+systemctl start gott
+echo "OK"
+```
+
+### Verzeichnisse
+
+- **Quell-Code**: `/app/gott/` (wwwroot/, Services/, etc.)
+- **Build-Output**: `/app/gott/publish/`
+- **Laufzeit-Daten**: `/app/gott/publish/data/` (DB, Agents, Images, Skills)
+- **WICHTIG**: Änderungen IMMER in `wwwroot/` machen, NIEMALS in `publish/wwwroot/`
+
+### systemd
+
+Die Anwendung läuft als systemd Service (`gott.service`), Kestrel auf Port 19000.
+
+---
+
+## Konfiguration
+
+### appsettings.json
+
+```json
+{
+  "AnthropicToken": "",         // Anthropic API Key (REQUIRED)
+  "MaxIterations": 100,         // Max Tool-Loop Iterationen pro Chat
+  "PayloadLogging": false,      // API-Payloads loggen (Debug)
+  "PayloadLoggingGzip": false,  // Payload-Logs als .gz komprimieren
+  "KreaToken": ""               // Krea API Token (optional)
+}
+```
+
+### Environment
+
+- `ASPNETCORE_ENVIRONMENT=Production` → lädt `appsettings.Production.json`
+- Tokens und Secrets sollten in `appsettings.Production.json` stehen (nicht in Git)
+
+---
+
+## Datenbank-Migrationen
+
+Die `DatabaseService.InitializeDatabase()` handhabt Schema-Erstellung und Migrationen in einem einzigen Methoden-Aufruf:
+
+1. **Tabellen-Erstellung** via `CREATE TABLE IF NOT EXISTS`
+2. **Spalten-Migration** via `TryAddColumn()` – fängt "column already exists" ab
+3. **Daten-Migration** (z.B. `auto_commit` von INTEGER zu TEXT, `use_web_search` zu `web_search_version`)
+
+Dieses Pattern ermöglicht:
+- Idempotente Ausführung bei jedem App-Start
+- Keine separate Migrations-Verwaltung nötig
+- Neue Features können einfach Spalten hinzufügen
+- Abwärtskompatibel – bestehende Daten bleiben erhalten