Neue Dokumentationsdateien

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "CodeGPT.apiKey": "Google AI Studio"
+}

docs/dev_workflow.md

@@ -0,0 +1,143 @@
+# Mindnet v2.2 – Entwickler-Workflow
+**Datei:** `DEV_WORKFLOW.md`
+**Stand:** 2025-12-07
+
+Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).
+
+---
+
+## 1. Die Architektur
+
+* **Windows 11 (VS Code):** Hier schreibst du Code. **Nie** direkt auf `main` arbeiten!
+* **Raspberry Pi (Gitea):** Der Tresor. Speichert den Code und verwaltet Versionen.
+* **Beelink (Runtime):** Hier läuft die Software. Wir trennen strikt:
+    * **PROD (`~/mindnet`):** Läuft stabil auf `main`. **Port 8001**.
+    * **DEV (`~/mindnet_dev`):** Deine Spielwiese für Branches. **Port 8002**.
+
+---
+
+## 2. Der Zyklus: Von der Idee zum Release
+
+### Phase 1: Entwicklung (Windows / VS Code)
+
+Hier erstellst du die neue Funktion in einer sicheren Umgebung.
+
+1.  **Sicherstellen, dass Git bereit ist:**
+    * Öffne VS Code.
+    * Unten links in der blauen Leiste sollte der aktuelle Branch stehen (z.B. `main`).
+
+2.  **Branch erstellen (WICHTIG):**
+    * Klicke unten links auf den Branch-Namen (z.B. `main`).
+    * Wähle im Menü oben `+ Create new branch...`.
+    * Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`).
+    * Drücke **Enter**.
+
+3.  **Sicherheits-Check:**
+    * Schau unten links: Steht dort jetzt `feature/wp04b-explanation`?
+    * **Nur wenn dort dein Feature-Branch steht, darfst du Code ändern!** Alles, was du jetzt speicherst, landet in diesem Branch.
+
+4.  **Coden:**
+    * Nimm deine Änderungen vor.
+
+5.  **Sichern & Hochladen:**
+    * Klicke links auf das **Source Control** Icon (Gabel-Symbol).
+    * Gib eine Nachricht ein: "feat: Add explanation layer logic".
+    * Klicke auf **Commit**.
+    * Klicke auf **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.
+
+---
+
+### Phase 2: Testen (Beelink / `mindnet_dev`)
+
+Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produktion zu stören.
+
+1.  **Einloggen:**
+    `ssh user@<BEELINK-IP>`
+
+2.  **In die Werkstatt gehen:**
+    `cd /home/llmadmin/mindnet_dev`
+
+3.  **Code holen:**
+    ```bash
+    git fetch
+    git checkout feature/wp04b-explanation
+    git pull
+    ```
+
+4.  **Umgebung aktivieren (Venv):**
+    Damit Python die installierten Bibliotheken findet, musst du das Virtual Environment aktivieren:
+    ```bash
+    source .venv/bin/activate
+    ```
+    *(Dein Prompt sollte jetzt `(.venv) user@...` zeigen)*
+
+5.  **Abhängigkeiten prüfen:**
+    *(Nur nötig, wenn du neue Libraries in `requirements.txt` eingetragen hast)*
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+6.  **Test-Server starten:**
+    **WICHTIG:** Nutze Port **8002** und das Dev-Prefix!
+    Stelle sicher, dass in `~/mindnet_dev/.env` steht: `COLLECTION_PREFIX="mindnet_dev"`.
+    
+    ```bash
+    uvicorn app.main:app --host 0.0.0.0 --port 8002
+    ```
+
+7.  **Testen:**
+    Prüfe deine Änderung (z.B. Browser auf `http://<BEELINK-IP>:8002/docs` oder Smoke-Test Skript).
+
+---
+
+### Phase 3: Release (Gitea / Raspberry Pi)
+
+Wenn der Test auf Port 8002 erfolgreich war:
+
+1.  Öffne Gitea im Browser.
+2.  Du solltest einen Hinweis sehen "feature/... had recent pushes".
+3.  Erstelle einen **Pull Request** (Dein Branch -> `main`).
+4.  **Merge** den Pull Request.
+
+---
+
+### Phase 4: Deployment (Beelink / `mindnet`)
+
+Jetzt bringen wir die Änderung in das Live-System (Port 8001).
+
+1.  **Deploy-Agent (Automatisch):**
+    Wenn dein `deploy.yml` aktiv ist, passiert das jetzt von selbst!
+
+2.  **Manuell (Falls nötig):**
+    ```bash
+    cd /home/llmadmin/mindnet
+    git pull origin main
+    sudo systemctl restart mindnet-api
+    ```
+
+---
+
+## 3. Cheat Sheet: Die wichtigsten Befehle
+
+| Wo? | Befehl | Was tut es? |
+| :--- | :--- | :--- |
+| **VS Code** | `Klick auf Branch-Namen` | Branch erstellen oder wechseln. |
+| **VS Code** | `Sync Changes` | Lädt Code zu Gitea hoch. |
+| **Beelink** | `cd ~/mindnet_dev` | Gehe in den Test-Ordner. |
+| **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** |
+| **Beelink** | `git fetch` | "Gibt es neue Branches auf Gitea?" |
+| **Beelink** | `git checkout <name>` | Wechsle auf einen anderen Branch. |
+| **Beelink** | `git pull` | Hol den neuesten Stand des aktuellen Branches. |
+| **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). |
+
+---
+
+## 4. Sicherheitsregeln
+
+1.  **Niemals** in `~/mindnet` (Prod-Ordner) experimentieren oder `git checkout` machen. Dieser Ordner bleibt immer auf `main`.
+2.  **Niemals** beide Umgebungen auf denselben `COLLECTION_PREFIX` zeigen lassen.
+    * Prod `.env`: `COLLECTION_PREFIX="mindnet"`
+    * Dev `.env`: `COLLECTION_PREFIX="mindnet_dev"`
+3.  **Port-Disziplin:**
+    * **PROD:** Port 8001
+    * **DEV:** Port 8002