Add packaged user manual and configuration guides to web console

docs/intake-api.md

@@ -4,7 +4,8 @@ Die API erstellt interne Case-Pakete und veröffentlicht sie atomar in der Inbox
 Externe Programme liefern Metadaten und Dateien; sie erzeugen und bearbeiten keine
 internen Manifeste. Die API führt keine Analyse und keine LLM-Aufrufe aus. Ein
 dauerhaft laufender [Analyseworker](analysis-worker.md) übernimmt anschließend die
-Aufnahme und Verarbeitung. Die allgemeine Weboberfläche bleibt ein weiterer Ausbauschritt.
+Aufnahme und Verarbeitung. Die [Weboberfläche](web-console.md) bietet Übersicht,
+Auftragsübergabe, Testerantworten und Ergebnisdownloads.
 
 ## Lokaler Start
 
@@ -17,7 +18,9 @@ $env:VBA_INTAKE_TOKEN = [Convert]::ToHexString([System.Security.Cryptography.Ran
 ```
 
 Der API-Token ist ein eigener Zugangsschlüssel, kein Gemini-Key. Programme erhalten
-je einen Client und einen Token aus einer serverseitigen Umgebungsvariable. Der
+vorzugsweise einen Schlüssel aus der [Web-Schlüsselverwaltung](integration-keys.md).
+Alternativ bleiben Clients mit Token aus einer serverseitigen Umgebungsvariable
+unterstützt; der Beispielstart oben zeigt diese Variante. Der
 Token benötigt 32–256 Zeichen aus `A-Z a-z 0-9 _ -`. Auf älterem Windows PowerShell
 kann ein solcher Token über einen Passwortmanager erzeugt und als Variable gesetzt
 werden. Der Beispielstart bindet nur an `127.0.0.1:8080`. Für entfernte Nutzung sind

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.

docs/test-results/user-manual-20261023.md

@@ -0,0 +1,42 @@
+# Benutzeranleitung in der Weboberfläche – 2026-10-23
+
+Ergebnis: eigener Reiter mit neun Dokumenten, Inhaltsverzeichnis, sicheren
+Markdown-Darstellungen und Markdown-Download. Neue allgemeine Bedienungs- und
+Funktionsbeschreibung sowie Projekt-/Source-/DB-/Modellkonfigurationsanleitung.
+Vorhandene Einrichtungsanleitungen werden eingebunden, nicht als Serverpfade
+verlinkt. Die Übergabe-API-Dokumentation wurde an den vorhandenen Webbetrieb
+und die Web-Schlüsselverwaltung angepasst.
+
+Quellen: `docs/` und `deploy/capture-worker/README.md`, feste Auswahlliste in
+`scripts/build_user_manual.py`. Die generierte Webressource wird mit dem Paket
+ausgeliefert. Ein Drift-Test verhindert unbemerkte Abweichungen von den Quellen.
+Keine tatsächlichen Konfigurationen oder Zugangsdaten im Bundle.
+
+Validierung:
+
+```text
+python -m pytest tests/test_user_manual.py tests/test_dashboard.py tests/test_web_auth.py tests/test_human_web.py -q
+28 passed, 1 dependency deprecation warning
+node tests/dashboard-smoke.mjs
+PASS, console_errors: [], overflow: false
+python scripts/build_user_manual.py --check
+PASS
+node --check src/viano_bug_analysis/web/user-manual.js
+PASS
+pip wheel --no-deps --no-index --no-build-isolation .
+PASS, manual JSON and renderer included in wheel
+```
+
+Nach Ergänzung des Pflegehinweises die manuelspezifischen Tests erneut bestanden.
+Browser prüft Login, Dokumentauswahl, Inhaltsverzeichnis, Linux-Befehle,
+Konfigurationstabellen, HTML-/URL-Abwehr im Renderer und Logout. Desktop- und
+Mobilansicht visuell kontrolliert. Quellen bleiben als Markdown separat pflegbar.
+Die Darstellung unterstützt die im Korpus verwendeten Überschriften, Listen,
+Tabellen, Codeblöcke, Inline-Code, Hervorhebungen und bekannte Dokumentverweise;
+beliebiges HTML wird als Text angezeigt.
+
+Vor lokalen Tests Trials 16.939.129.428 Bytes und Fehlerkorpus 2.471.041 Bytes;
+kleine temporäre synthetische Testdaten und Paket-Builds halten das Gesamtbudget
+weiter unter 20 GB. Temporäres Wheel nach Prüfung entfernt. Keine realen
+Fallkopien, Modellanfragen, Cloudkosten, Dienststarts oder Serveränderungen.
+`docs/architecture.md` unverändert. Kein Push.

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.

docs/web-console.md

@@ -15,6 +15,25 @@ Für entfernte Zugriffe HTTPS verwenden. Der Analyseworker läuft unabhängig da
 [Analyseworker](analysis-worker.md) beschrieben. Das Öffnen der Übersicht löst
 keine Modellanfragen aus.
 
+## Benutzeranleitung
+
+Der Reiter **Benutzeranleitung** enthält die allgemeine Bedienung und
+Funktionsweise sowie Anleitungen für Linux, Projekt-/DB-/Sourcekonfiguration,
+Übergabe-API, Analyseworker, Nutzerkonten, Integrationsschlüssel, Weboberfläche
+und Erfassungsworker. Dokumentauswahl, Inhaltsverzeichnis und interne Verweise
+erlauben Navigation ohne Server-Dateizugriff. Markdown-Downloads sind ebenfalls
+möglich. Der Reiter benötigt eine angemeldete Sitzung; sein Aufruf startet keine
+Analyse. Tabellen, Codebeispiele und Überschriften werden als sichere DOM-Elemente
+dargestellt, eingebettetes HTML wird nicht ausgeführt.
+
+Für Dokumentationsänderungen die ursprünglichen Markdown-Dateien unter `docs/`
+beziehungsweise `deploy/capture-worker/README.md` bearbeiten und danach
+`python scripts/build_user_manual.py` ausführen. Die feste Auswahlliste steht im
+Skript; tatsächliche lokale Konfigurationen oder Secrets werden nicht gebündelt.
+`python scripts/build_user_manual.py --check` und die Tests erkennen veraltete
+Webfassungen. Das erzeugte `web/user-manual.json` wird mit dem Python-Paket
+ausgeliefert, sodass keine lokale Kopie des Dokumentationsordners nötig ist.
+
 ## Worker und Fortschritt
 
 Die Startseite listet lebende Worker und darunter den jeweils bearbeiteten Fall