fix(gtm-architect): Stabilize Docker environment and fix frontend

- Refactor Docker build process for gtm-app to ensure reliability
- Correct volume mounts and build context in docker-compose.yml to prevent stale code
- Fix frontend 404 error by using relative paths in index.html
- Ensure API key is correctly mounted into the container
- Stabilize Node.js to Python data passing via explicit --data argument
- Update gtm_architect_documentation.md with extensive troubleshooting guide

gtm_architect_documentation.md

@@ -63,28 +63,46 @@ Der Service läuft im Container `gtm-architect`.
 *   **Optimierung:** Nur `/dist` und Skripte landen im finalen Image.
 *   **Mounts:**
     *   `gtm_projects.db` (Persistenz)
+    *   `gemini_api_key.txt` (API-Schlüssel)
     *   `gtm_architect_orchestrator.py` (Sideloading für Dev)
     *   `server.cjs` (Sideloading für Dev)
     *   `helpers.py` & `config.py` (Shared Libraries)
 
 ### Starten / Neustarten
-```bash
-# Bauen und Starten
-docker-compose up -d --build gtm-app proxy dashboard
+Der beste Weg, um einen sauberen Neustart zu gewährleisten, ist der `up`-Befehl mit `--build`.
 
-# Nur Neustart nach Python-Änderungen (dank Sideloading)
-docker-compose restart gtm-app
+```bash
+# Kompletten Stack neu bauen und starten (empfohlen)
+docker-compose up -d --build
+
+# Nur den gtm-app Service neu bauen & neu erstellen
+# Das --force-recreate ist entscheidend, um sicherzustellen, dass der alte Container ersetzt wird.
+docker-compose up -d --build --force-recreate gtm-app
+
+# Build ohne Cache erzwingen (bei hartnäckigen Problemen)
+docker-compose build --no-cache gtm-app && docker-compose up -d gtm-app
 ```
 
 ## 5. Wartung & Troubleshooting
 
+### Fehler: "White Screen" / Leere Seite nach Start
+*   **Symptom:** Der Browser zeigt eine leere Seite. In der Entwicklerkonsole erscheint ein `404 Not Found` Fehler für `index.css` oder `index.tsx`.
+*   **Ursache:** Falsche Pfade in der `gtm-architect/index.html`. Die `href` und `src` Attribute für CSS und JS müssen relativ (`./index.css`) statt absolut (`/index.css`) sein.
+*   **Lösung:** Pfade in der `index.html` korrigieren und sicherstellen, dass in `vite.config.ts` die Option `base: './'` gesetzt ist. Anschließend den Container mit `--build` neu erstellen.
+
+### Fehler: Leere Listen / Keine API-Antwort im Frontend
+*   **Symptom:** Die App startet, aber nach dem Klick auf "Analyse starten" erscheinen keine Features oder Constraints. Es gibt keine Fehlermeldung.
+*   **Ursache:** Dem Python-Skript fehlt der API-Schlüssel. Das Skript `config.py` liest den Schlüssel aus der Datei `/app/api_key.txt` im Container. Wenn diese Datei fehlt, schlagen API-Aufrufe im Hintergrund fehl, und das Skript gibt eine leere Antwort zurück.
+*   **Lösung:** Sicherstellen, dass die `docker-compose.yml` den API-Schlüssel korrekt in den Container mountet: `volumes: - ./gemini_api_key.txt:/app/api_key.txt`.
+
+### Fehler: Code-Änderungen werden nicht übernommen (Stale Code)
+*   **Symptom:** Änderungen an Python- oder Node.js-Dateien haben keine Auswirkung im Container, selbst nach einem `restart`.
+*   **Ursache:** Ein Problem in der `docker-compose.yml`. Entweder ist der `build context` falsch gesetzt oder die `volumes`-Konfiguration für das Sideloading ist fehlerhaft. Ein zu breiter Mount wie `- .:/app` kann von den Dateien im Image überschrieben werden.
+*   **Lösung:**
+    1.  Den `build context` auf `.` setzen und das `dockerfile` spezifisch adressieren (`gtm-architect/Dockerfile`).
+    2.  `volumes` für jede zu sideloadende Datei einzeln und explizit definieren.
+    3.  Den Container mit `docker-compose up -d --build --force-recreate gtm-app` neu erstellen.
+
 ### Fehler: "502 Bad Gateway"
 *   **Ursache:** Der Node.js Server oder Nginx hat den Request wegen Timeout abgebrochen.
 *   **Lösung:** Timeouts sind in `nginx-proxy.conf` und `server.cjs` auf 600s+ gesetzt. Prüfen, ob der Container läuft (`docker ps`).
-
-### Fehler: "Project not saved"
-*   **Ursache:** Berechtigungsprobleme auf `gtm_projects.db` oder Datei fehlt.
-*   **Lösung:** Sicherstellen, dass die Datei auf dem Host existiert und gemountet ist (wurde im Setup-Prozess via `touch` erstellt).
-
-### Entwicklung
-Änderungen am Prompting sollten ausschließlich in `gtm_architect_orchestrator.py` vorgenommen werden. Nach der Änderung reicht ein `docker-compose restart gtm-app`.