Add packaged user manual and configuration guides to web console

docs/project-configuration.md

@@ -0,0 +1,114 @@
+# Projekt und Recherchezugriffe konfigurieren
+
+Die Projektkonfiguration wird über Dateien verwaltet, nicht über die Webseite.
+Sie legt fest, welche Werkzeuge ein Auftrag verwenden darf. Ein aufrufendes
+Programm kann weder Repository noch DB-Zugänge oder Budgets mit einem Auftrag
+überschreiben. Aktuell ist das Profil `wow/vcore` mit dem Importadapter `vcore`
+implementiert; andere Projekttypen erfordern entsprechende Adapter und Profile.
+
+## Zuordnung in api.toml
+
+Ein Projektelement ordnet eine feste Projekt-ID einem Profil und dessen
+Konfigurationsdateien zu. Relative Pfade beziehen sich auf die API-Konfigurationsdatei.
+Der Erfassungsworker muss genau dieselbe Projekt-/Profilzuordnung senden und
+sein Integrationsschlüssel muss für das Projekt freigegeben sein.
+
+```toml
+[[projects]]
+id = "viano-core"
+type = "wow"
+profile = "vcore"
+adapter = "vcore"
+planning_mode = "joint"
+[projects.settings]
+project_config = "project.toml"
+llm_config = "llm.toml"
+investigation_config = "investigation.bounded.toml"
+budget_config = "budget.human-tests.toml"
+```
+
+Die Linux-Vorlagen stehen unter `deploy/linux/`; der Installer legt die
+Konfiguration unter `/etc/viano-bug-analysis` an. Er überschreibt bestehende
+Dateien nicht. Die ausführliche Vcore-Projektvorlage steht unter
+`config/project.example.toml`, die Relationsregeln unter
+`config/project-relations.vcore.toml`.
+
+## Source und Datenbank in project.toml
+
+```toml
+relations_file = "project-relations.vcore.toml"
+[project]
+type = "wow"
+profile = "vcore"
+
+[source]
+path = "/srv/viano-bug-analysis/viano-core"
+url = "https://gitea.viano-software.de/Nico/Viano-Core"
+commit = "VOLLSTAENDIGEN_40_STELLIGEN_COMMIT_EINTRAGEN"
+
+[database]
+host = "127.0.0.1"
+port = 3306
+database = "cata_world"
+user = "viano_reader"
+password_env = "VIANO_DB_PASSWORD"
+snapshot_id = "KENNUNG_DER_TATSAECHLICHEN_DATENGRUNDLAGE"
+tables = ["creature_template", "creature"]
+```
+
+Das Beispiel zeigt nur den Aufbau und enthält absichtlich ungültige Platzhalter.
+Die beiden Tabellen sind keine vollständige Vcore-Freigabeliste. Für das echte
+Profil die vollständige Vorlage einschließlich Limits, Enrichment und
+Analysewerkzeugregeln verwenden und passend prüfen.
+
+Der Source-Checkout muss lokal vorhanden sein und den konfigurierten Commit
+enthalten. Die URL allein klont oder aktualisiert kein Repository. Der Worker
+liest Git-Objekte dieses festen Stands und benötigt keine Schreibrechte auf den
+Checkout. Die Linux-Vorlage enthält eine gezielte Git-Vertrauenskonfiguration
+für den root-eigenen Checkout. Neue Source-Stände bewusst bereitstellen und
+deren vollständigen Commit konfigurieren.
+
+Der DB-Administrator legt einen Benutzer mit ausschließlich passenden SELECT-
+Rechten an. Zusätzlich begrenzt `tables` die zugänglichen Tabellen. Diese
+Freigabeliste ersetzt keine serverseitigen Rechte. Account- oder Charakterdaten
+gehören nicht zur standardmäßigen World-Recherche. Für entfernte DBs einen
+geschützten Netzwerkweg nutzen; der aktuelle Provider konfiguriert selbst kein TLS.
+
+Das Passwort steht entweder in der durch `password_env` benannten
+Umgebungsvariable oder einer separaten geschützten Datei über `password_file`.
+Nur eine dieser Varianten setzen. Unter Linux lädt der Worker beispielsweise
+`VIANO_DB_PASSWORD` aus seiner root-geschützten `worker.env`.
+Passwörter nicht in Fallakten, LLM-Prompts oder Versionsverwaltung ablegen.
+Die LLM bekommt Werkzeugergebnisse statt Zugangsdaten.
+
+## Weitere Konfigurationen
+
+| Datei | Zuständigkeit |
+| --- | --- |
+| api.toml | HTTP-Bindung, Workspace, Projekte, Nutzerdatei und optionale env-basierte Maschinenclients |
+| worker.toml | Verweis auf api.toml, Polling, Wiederholungsabstände, Speicherreserve und Telemetrie |
+| llm.toml | Anbieter, Modell, Schlüssel-Environment, Timeouts, Ausgabe-/Denkeinstellungen und Cache |
+| investigation.bounded.toml | Untersuchungsmodus und begrenztes Kontextfenster |
+| budget.human-tests.toml | Fachliche Budgetregeln und menschliche Testanfragen |
+| telemetry.toml | Heartbeats und lokale Betriebsbeobachtung |
+| project-relations.vcore.toml | Projektspezifische Beziehungen für Recherchewerkzeuge |
+
+Die versionierte Modellvorlage `config/llm.gemini-cache.example.toml` verwendet
+`GEMINI_API_KEY`. Das ist unabhängig vom Integrationsschlüssel für externe
+Auftragsübergaben. Die API erhält `api.env`; der Analyseworker erhält
+`worker.env` mit Cloud- und DB-Zugangsdaten.
+
+## Prüfen und ändern
+
+Der Befehl `python -m viano_bug_analysis.deployment check` prüft mit Rolle und
+Konfigurationspfad die Betriebsbereitschaft ohne Modellanfrage. Die
+[Linux-Anleitung](linux-deployment.md) zeigt die vollständigen Befehle unter der
+tatsächlichen Dienstidentität. Die Prüfung umfasst Git-Objekte und freigegebene
+DB-Schemata; die Gültigkeit des Cloud-Schlüssels wird nicht durch einen bezahlten
+Modellaufruf getestet. `--offline` prüft keine Git-/DB-Verbindung.
+
+Vor Code- oder Profiländerungen den Worker kontrolliert anhalten und die
+Auswirkungen auf laufende Akten prüfen. Der Worker bindet Fälle an ihren
+Konfigurationsstand. Eine Änderung ist kein Weg zum Zurücksetzen von Budgets;
+abweichende Bindungen können eine Betreiberprüfung erfordern. Bestehende Dateien
+und Zugangsdaten vor Änderungen sichern.