Add packaged user manual and configuration guides to web console

docs/user-guide.md

@@ -0,0 +1,153 @@
+# BugAnalysis verwenden
+
+BugAnalysis untersucht gemeldete Softwarefehler und übergibt das Ergebnis an die
+nächste zuständige Stelle. Das Programm erstellt selbst keinen fertigen Patch
+und spielt keine Änderungen auf einen Server ein. Der aktuelle Erfassungsadapter
+ist für WoW/Vcore eingerichtet.
+
+## So arbeitet BugAnalysis
+
+1. Eine Person oder ein Erfassungsprogramm übergibt Bugbeschreibung und
+   Diagnosearchive. Die Übergabe-API erstellt daraus eine Fallakte.
+2. Ein dauerhaft laufender Analyseworker übernimmt den Auftrag und lädt die
+   Konfiguration des angegebenen Projekts.
+3. Der Casebuilder wertet Beobachtungen und Telemetrie aus. Er kann relevante
+   Identitäten mit den konfigurierten Recherchewerkzeugen auflösen.
+4. Die LLM interpretiert den Fall und entwickelt Hypothesen. Im gemeinsamen
+   Planungsmodus geschieht beides in einem Aufruf.
+5. Die Untersuchung prüft Hypothesen mit Source- und DB-Werkzeugen. Eine knappe
+   Untersuchungsschleife sammelt Ergebnisse; Prüfungen und Konsolidierungen
+   übernehmen diese in den strukturierten Arbeitsstand. Werkzeuge lesen Daten;
+   Zugangsdaten erhält die LLM nicht.
+6. Die finale Diagnose bewertet die Befunde und kann einen Frühabschluss
+   annehmen oder weitere Untersuchung verlangen. Fachliche Budgets begrenzen
+   einzelne Untersuchungen. Ein bestimmter Erfolg ist nicht garantiert.
+7. Das Ergebnis enthält Diagnose und Aufträge für Codingagent und menschlichen
+   Entwickler. Ein Auftrag darf ausdrücklich erklären, dass keine Arbeit für
+   den jeweiligen Empfänger vorliegt. Fehlende Daten zur Umsetzung können als
+   menschlicher Auftrag übergeben werden, ohne die erfolgreiche Analyse zu sperren.
+
+Ein Ergebnis bleibt eine begründete Analyse, keine Garantie für einen wirksamen
+Fix. Nach Umsetzung und Tests können Rückmeldungen eine neue Analyserevision
+derselben Akte auslösen. Behauptungen, Testerbeobachtungen und bestätigte Befunde
+sollten bei der Bewertung auseinandergehalten werden.
+
+## Anmeldung und Start
+
+Die Webadresse im Browser öffnen und mit Benutzername und Passwort anmelden.
+Benutzerkonten werden ausschließlich per privilegierter Konsole angelegt;
+eine Selbstregistrierung gibt es nicht. Alle menschlichen Benutzer haben die
+gleichen Rechte für alle Projekte. Externe Programme benutzen eigene
+Integrationsschlüssel mit Projektfreigaben.
+
+API und Analyseworker sind getrennte Dienste. Das Öffnen der Webseite startet
+keinen Worker und sendet keine Modellanfrage. Der laufende Worker verarbeitet
+Aufträge selbstständig; die Webseite ist die Übersicht und alternative Bedienung.
+
+## Übersicht und laufende Fälle
+
+Die Übersicht zeigt erreichbare Worker, den bearbeiteten Fall und dessen
+Fortschrittsbalken. Der Balken folgt abgeschlossenen Phasen, nicht vergangener
+Zeit. Während einer längeren Untersuchung kann er daher unverändert bleiben.
+Abgeschlossene Fälle verschwinden aus der aktiven Workeransicht.
+
+Die Diagramme zeigen gemessenen Tokenverbrauch. Korrektur- und Wiederholungsaufrufe
+bilden eine eigene Kategorie. Denktokens sind bereits in den Ausgabetokens
+enthalten und werden nicht doppelt addiert. Fehlende Messwerte werden als solche
+ausgewiesen. Diese Zahlen sind keine verbindliche Cloud-Abrechnung und umfassen
+nur die erhaltenen Akten im gewählten Messumfang.
+
+Über Fallnummern lässt sich die Detailansicht öffnen: Beobachtungen, Einordnung,
+Hypothesen, Befunde, Diagnose und Aufträge. Frühere Revisionen bleiben über die
+Revisionsauswahl einsehbar. Die vollständigen Daten stehen im herunterladbaren ZIP.
+
+## Neue Aufträge und Rückgaben
+
+Unter **Auftrag übergeben** Projekt, Bug-ID, Fallname und Beobachtungen eingeben.
+Für einen neuen Vcore-Fall das wowdiag-Archiv und möglichst das dazugehörige
+wowsrc-Archiv derselben Erfassung auswählen. Die Bug-ID muss mit den Archiven
+übereinstimmen. Zusätzliche Dateien lassen sich als Anhänge hinzufügen.
+
+Nach dem Absenden bestätigt die API die Annahme. Das ist noch kein Analyseerfolg.
+Bei einer unterbrochenen Übergabe verwendet das Formular bei unveränderten
+Eingaben denselben Idempotenzschlüssel, damit kein doppelter Auftrag entsteht.
+
+Für eine Rückgabe den Auftragstyp **Abgeschlossene Akte zurückgeben** wählen,
+die aktuelle abgeschlossene Case-ZIP hochladen und Ergebnis sowie neue
+Beobachtungen eintragen. Beispielsweise kann ein getesteter Patch den Fehler
+nicht behoben haben. BugAnalysis ergänzt die Akte und öffnet eine neue Revision.
+Blockierte oder noch laufende Akten sind keine Abschlussrückgaben.
+
+Automatische Erfassung erfolgt über den wowdiag-Worker und dieselbe Übergabe-API.
+Externe Programme erstellen keine internen Case-Manifeste selbst.
+
+## Testanfragen beantworten
+
+Die Seite **Testanfragen** listet offene menschliche Recherche- und Testfragen
+mit Projekt. Nach Zeitpunkt oder Projekt sortieren, eine Anfrage auswählen und
+zunächst **Bearbeiten** drücken. Erst dann wird das Antwortformular freigegeben.
+
+Die Anfrage ist während der Session exklusiv gebunden. Andere Personen können
+sie nicht gleichzeitig bearbeiten. Beobachtungen und verlangte Angaben sachlich
+eintragen und absenden. Bei Sessionablauf oder Abmeldung wird die Bearbeitung
+wieder freigegeben. Nach gültiger Antwort setzt der Worker die Analyse mit dem
+vorhandenen Stand fort; fachliche Budgets werden nicht erneuert.
+
+Eine Testanfrage während der Ursachenklärung ist etwas anderes als ein
+Human-Dev-Auftrag im fertigen Ergebnis. Letzterer gehört zur weiteren Umsetzung.
+
+## Bearbeitete Fälle und Downloads
+
+Unter **Bearbeitete Fälle** stehen Ergebnisse, übergebene Fälle, blockierte Fälle
+und gescheiterte Analysen in einer gemeinsamen Liste. Projekt, Kategorie und
+Suchbegriff können kombiniert werden; die Sortierung ist separat wählbar.
+Links lädt der Pfeilknopf die aktuelle vollständige Fallakte als ZIP herunter.
+Ein Download ändert den Fallstatus nicht und bestätigt keine Übergabe.
+
+| Zustand | Bedeutung |
+| --- | --- |
+| Ergebnis bereit / OUTPUT_READY | Analyseergebnis für die weitere Bearbeitung; Routingziel Outbox |
+| Übergeben / HANDED_OFF | Die Akte wurde intern als übergeben markiert |
+| Blockiert / BLOCKED | Analyse wartet, beispielsweise auf Testerantwort oder technische Behebung |
+| Analyse gescheitert / FAILED_TO_ANALYZE | Analyse konnte nicht erfolgreich abschließen; Routingziel Review |
+
+Blockiert bedeutet nicht abgeschlossen. Sperrgrund und Detailansicht erklären
+die nächsten Schritte. Technische Fehler oder unzureichende Eingaben sind von
+einem fachlichen Diagnoseergebnis zu unterscheiden. Die Ablagespalte zeigt das
+Routingziel, keinen unabhängigen Verzeichnisbestand.
+
+## Betrieb steuern
+
+Die Betriebssteuerung in der Übersicht erlaubt das Pausieren neuer Fälle eines
+Projekts. Bereits begonnene Fälle dürfen weiterlaufen. Geeignete technische
+Fehlerfälle können über eine Fortsetzungsanforderung nach Behebung wieder
+freigegeben werden. Diese Aktion ist kein beliebiger Neustart und setzt keine
+Budgets zurück. Menschliche Testantworten werden auf ihrer eigenen Seite erfasst.
+
+## Programme anbinden
+
+Unter **API-Schlüssel** einen Programmnamen und die erlaubten Projekte auswählen.
+Den erzeugten Schlüssel über **Anzeigen** oder **Kopieren** abrufen und im
+aufrufenden Dienst geschützt hinterlegen. Schlüssel sind später erneut anzeigbar.
+**Widerrufen** verhindert weitere authentifizierte Anfragen mit diesem Schlüssel.
+
+Die Schlüssel dienen zur Auftragsübergabe und zum lesenden Projektzugriff;
+Maschinenprogramme können darüber keine anderen Schlüssel verwalten oder
+menschliche Testerantworten ausfüllen. Ein Integrationsschlüssel ist kein
+Gemini- oder anderer Modellanbieter-Schlüssel.
+
+## Einrichtung und Hilfe
+
+- [Linux-Installation und Betrieb](linux-deployment.md)
+- [Projekt-, Source-, DB- und Modellkonfiguration](project-configuration.md)
+- [Übergabe-API und Rückgaben](intake-api.md)
+- [Analyseworker und Wiederanlauf](analysis-worker.md)
+- [Benutzerkonten](user-accounts.md)
+- [Integrationsschlüssel und deren Sicherung](integration-keys.md)
+- [Weboberfläche im Detail](web-console.md)
+- [Erfassungsworker v0.4](capture-worker.md)
+
+Vor dem ersten Feldbetrieb auf dem Zielserver Bereitschaftsprüfung, HTTPS,
+Dienstneustart und Backups prüfen. Danach einen kontrollierten echten Auftrag
+einschließlich Rückfrage und Ergebnisabholung durchführen. Die LLM-Zugriffe
+erzeugen erst beim laufenden Analysebetrieb Kosten.