# VianoBugAnalysis

BugAnalysis untersucht gemeldete Softwarefehler anhand von Diagnosepaketen,
Sourcecode und lesenden Datenbankabfragen. Ein dauerhaft laufender Worker erstellt
Diagnosen und Aufträge für Codingagenten beziehungsweise menschliche Entwickler.
Die Weboberfläche bietet Benutzeranmeldung, Betriebsübersicht, Testerantworten,
API-Schlüssel und Paketdownloads. Das aktuelle Projektprofil ist für WoW/Vcore
ausgelegt. BugAnalysis installiert selbst keine Bugfixes auf dem Spielserver.

## Installation auf einem Linux-VPS

Diese Anleitung ist direkt auf der Repository-Startseite lesbar. Sie setzt einen
Linux-Server mit systemd und einen SSH-Zugang mit sudo-Rechten voraus. Die
Paketbefehle unten gelten für Debian/Ubuntu; auf anderen Distributionen die
entsprechenden Pakete installieren. **Python 3.11 oder neuer ist erforderlich.**

### 1. Voraussetzungen installieren

```sh
sudo apt-get update
sudo apt-get install python3 python3-venv python3-pip git nginx ca-certificates curl
python3 --version
```

Ist die Python-Version älter als 3.11, zuerst eine unterstützte Python-Version
bereitstellen und diese für den Installer verwenden. Datenbankserver und
World-Daten werden vom Installer nicht eingerichtet oder importiert. Ein
erreichbarer MariaDB-Datenbestand für die Recherche muss separat vorhanden
sein, beispielsweise eine isolierte Testdatenbank aus einem Backup.

### 2. Repository in das vorgesehene Verzeichnis klonen

**Der Installer und die systemd-Units erwarten derzeit genau
`/opt/viano-bug-analysis`.** Nicht einen beliebigen Ordnernamen verwenden.
Git legt den Zielordner an; er muss dafür noch nicht existieren oder leer sein.

```sh
sudo git clone https://gitea.viano-software.de/Nico/VianoBugAnalysis /opt/viano-bug-analysis
cd /opt/viano-bug-analysis
```

Das Klonen mit sudo erzeugt einen root-eigenen Checkout. Der Installer verlangt,
dass Programmdateien root gehören und weder für Gruppe noch andere Benutzer
schreibbar sind. Bei einem privaten Repository die Git-Anmeldung interaktiv
durchführen; keine Zugangsdaten in die URL schreiben.

### 3. Installationsplan prüfen und installieren

```sh
python3 deploy/install.py --dry-run
sudo python3 deploy/install.py
```

Der erste Befehl zeigt nur den Plan. Der zweite erstellt den Dienstbenutzer
`buganalysis`, die virtuelle Python-Umgebung, Konfigurationsvorlagen und beide
systemd-Units. Er startet oder aktiviert noch keinen Dienst und sendet keine
LLM-Anfrage. Vorhandene Konfigurationsdateien und Units werden nicht überschrieben.

| Verzeichnis | Inhalt |
| --- | --- |
| `/opt/viano-bug-analysis` | Programmcode und `.venv`; root-verwaltet |
| `/etc/viano-bug-analysis` | Konfiguration, geschützte Environment-Dateien und Webnutzerdatei |
| `/var/lib/viano-bug-analysis` | Fallakten, Inbox, Outbox, Review und Laufzeitdaten |
| `/srv/viano-bug-analysis/viano-core` | Separater Source-Checkout des untersuchten Vcore-Projekts |

Der Linux-Dienstbenutzer ist kein Webkonto. Webkonten werden in Schritt 6
gesondert angelegt. Ein Programm zur automatischen Erfassung benötigt später
einen Integrationsschlüssel, ebenfalls kein Webpasswort oder Cloud-API-Key.

### 4. Vcore-Sourcecode und lesenden Datenbankzugang bereitstellen

BugAnalysis benötigt zusätzlich zu seinem eigenen Repository den Sourcecode des
untersuchten Projekts. Für Vcore beispielsweise:

```sh
sudo git clone --branch master --single-branch https://gitea.viano-software.de/Nico/Viano-Core /srv/viano-bug-analysis/viano-core
sudo git -C /srv/viano-bug-analysis/viano-core rev-parse HEAD
```

Die Ausgabe des zweiten Befehls ist der vollständige Commit. Der für die Analyse
gewünschte Stand muss lokal vorhanden sein und wird in `project.toml` festgelegt.
Der aktuelle Branchkopf ist nur dann passend, wenn genau dieser Stand untersucht
werden soll. Der Worker klont oder aktualisiert den Sourcecode nicht automatisch.

Ein DB-Administrator richtet einen Benutzer mit ausschließlich passenden
SELECT-Rechten auf die World-Daten ein. Keine Schreibrechte und keinen
allgemeinen Administrationszugang verwenden. Für entfernte Datenbanken einen
geschützten Netzwerkweg bereitstellen; der aktuelle DB-Provider richtet selbst
kein TLS ein. Die vollständige Tabellenfreigabe steht in der Projektvorlage.

### 5. Konfigurationen und Zugangsdaten eintragen

Die Konfiguration liegt außerhalb des Git-Checkouts. Beispiele öffnen:

```sh
sudoedit /etc/viano-bug-analysis/api.toml
sudoedit /etc/viano-bug-analysis/project.toml
sudoedit /etc/viano-bug-analysis/llm.toml
sudoedit /etc/viano-bug-analysis/worker.env
```

| Datei | Beim ersten Einrichten prüfen |
| --- | --- |
| `api.toml` | Projekt-ID, Profilzuordnung und Konfigurationspfade; HTTP-Bindung auf `127.0.0.1:8080` lassen |
| `project.toml` | Sourcepfad und vollständigen Commit, DB-Host/Port/Name/Benutzer, Snapshotkennung und Tabellenfreigaben |
| `llm.toml` | Anbieter, tatsächlich verfügbares Modell, Cache- und Timeout-Einstellungen; verwendete Schlüssel-Umgebungsvariable |
| `worker.env` | Cloud-API-Key und DB-Passwort |
| `worker.toml` | Verweis auf `api.toml`, Polling und Speicherreserve; Vorgaben zunächst übernehmen |
| `investigation.bounded.toml`, `budget.human-tests.toml` | Untersuchungs- und Budgetregeln; Vorgaben zunächst übernehmen |
| `telemetry.toml` | Betriebsbeobachtung; Vorgaben zunächst übernehmen |

In `project.toml` die Null-Commit- und `CONFIGURE_ME`-Platzhalter ersetzen. Die
vollständige Vorlage mit Relations-, Enrichment- und Werkzeugregeln beibehalten;
die Projektdatei nicht auf DB-Adresse und Sourcepfad zusammenkürzen.

Für mehrere Datenbanken derselben MariaDB-Instanz kann in `project.toml` ein
zusätzlicher Abschnitt ergänzt werden:

```toml
[database.additional_databases]
cata_hotfixes = ["*"]
cata_locale = ["*"]
```

`[database].database` bleibt beispielsweise `cata_world`, `user` kann
`buganalysis` sein. Für den DB-Benutzer müssen entsprechende SELECT-Grants
vorliegen. `["*"]` erlaubt ausdrücklich alle sichtbaren Tabellen der jeweiligen
DB. Alternativ konkrete Tabellennamen auflisten. Nicht konfigurierte Datenbanken
bleiben gesperrt. Einzeldatenbank-Konfigurationen bleiben gültig.
Vollständige Mehrdatenbank-Vorlage:
[project.vcore-multidb.example.toml](config/project.vcore-multidb.example.toml).

Bei Verwendung der gelieferten Gemini-/DB-Vorlagen enthält `worker.env`:

```text
GEMINI_API_KEY="HIER_DEN_CLOUD_API_KEY_EINTRAGEN"
VIANO_DB_PASSWORD="HIER_DAS_DB_PASSWORT_EINTRAGEN"
```

Das sind Platzhalter, keine gültigen Zugangsdaten. Keine `export`-Anweisungen
verwenden. Die Datei wird durch systemd geladen und bleibt root-geschützt mit
Modus 0600. Secrets nicht ins Repository oder in Shell-Befehlsargumente schreiben.

**Wenn Integrationsschlüssel über die Weboberfläche verwaltet werden sollen:**
Den ausgelieferten `[[clients]]`-Beispielblock für `wow-capture-worker` vollständig
aus `api.toml` entfernen. Dazu gehören seine `id`-, `token_env`- und `projects`-
Zeilen. Die `[[projects]]`-Projektdefinition bleibt bestehen. `api.env` darf dann
zunächst nur Kommentare enthalten; ein `VBA_INTAKE_TOKEN` ist auf der
BugAnalysis-Seite nicht erforderlich. Andernfalls erwartet die Startprüfung für
den vorhandenen Beispielclient einen manuell konfigurierten Token in `api.env`.

Details: [Projektkonfiguration](docs/project-configuration.md),
[Modell-/Cachekonfiguration](docs/llm-context-caching.md) und
[Linux-Betrieb](docs/linux-deployment.md).

### 6. Persönliches Webkonto anlegen

`meinname` durch den gewünschten Benutzernamen ersetzen. Das Passwort wird
verdeckt abgefragt; es gehört nicht in die Befehlszeile.

```sh
sudo /opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.api create_user meinname --config /etc/viano-bug-analysis/api.toml --service-group buganalysis
```

Alle Webnutzer besitzen dieselben Bedienrechte. Nutzer werden ausschließlich per
privilegierter Konsole angelegt, geändert oder gelöscht; es gibt keine öffentliche
Registrierung. Weitere Befehle: [Benutzerkonten](docs/user-accounts.md).

### 7. Bereitschaft ohne Modellanfrage prüfen

Die Prüfungen laufen mit den Rechten und Environment-Dateien der späteren Dienste:

```sh
sudo systemd-run --wait --pipe --collect \
  --property=User=buganalysis --property=Group=buganalysis \
  --property=EnvironmentFile=/etc/viano-bug-analysis/api.env \
  /opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.deployment check \
  --role api --config /etc/viano-bug-analysis/api.toml

sudo systemd-run --wait --pipe --collect \
  --property=User=buganalysis --property=Group=buganalysis \
  --property=EnvironmentFile=/etc/viano-bug-analysis/worker.env \
  --setenv=GIT_CONFIG_GLOBAL=/etc/viano-bug-analysis/gitconfig \
  /opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.deployment check \
  --role worker --config /etc/viano-bug-analysis/worker.toml
```

Erwartet wird jeweils `READY` mit `model_requests: 0`. Geprüft werden unter
anderem Speicher, Schreib-/Leserechte, Webnutzer, Konfiguration, Git-Stand und
DB-Schemata. Die Prüfung sendet keine kostenpflichtige Modellanfrage; sie bestätigt
deshalb nicht die Gültigkeit des Cloud-Keys oder die Modellverfügbarkeit.
Bei `NOT_READY` zunächst den gemeldeten Fehler beheben.

### 8. API starten und HTTPS einrichten

```sh
sudo systemd-analyze verify /etc/systemd/system/viano-bug-analysis-api.service /etc/systemd/system/viano-bug-analysis-worker.service
sudo systemctl enable --now viano-bug-analysis-api.service
curl --fail http://127.0.0.1:8080/healthz
```

Der Health-Aufruf auf dem VPS sollte `{"status":"OK"}` liefern. Die API bleibt
an Loopback gebunden. Für die öffentliche Webadresse eine Domain mit passendem
DNS-Eintrag und gültigem TLS-Zertifikat bereitstellen. Zertifikatsbeschaffung
und Firewallfreigaben an die vorhandene VPS-/Nginx-Einrichtung anpassen.

Auf Debian/Ubuntu kann eine eigene Nginx-Site aus der Vorlage angelegt werden:

```sh
sudo cp /etc/viano-bug-analysis/nginx.conf.example /etc/nginx/sites-available/viano-bug-analysis
sudoedit /etc/nginx/sites-available/viano-bug-analysis
sudo ln -s /etc/nginx/sites-available/viano-bug-analysis /etc/nginx/sites-enabled/viano-bug-analysis
sudo nginx -t
sudo systemctl enable --now nginx
sudo systemctl reload nginx
```

**Vor `nginx -t` alle Beispieldomains und Zertifikatpfade ersetzen; die Zertifikate
müssen bereits vorhanden sein.** Bei bereits vorhandener Site keinen zweiten
Symlink anlegen, sondern die bestehende Einrichtung prüfen. Andere VPS-Sites
nicht entfernen. Erst über die fertige HTTPS-Adresse öffentlich anmelden.

Für einen ersten lokalen Zugriff ohne fertige Domain ist ein SSH-Tunnel möglich.
Auf deinem eigenen Rechner ausführen, mit deinem SSH-Benutzer und VPS-Host:

```sh
ssh -L 8080:127.0.0.1:8080 benutzer@vps-host
```

Danach lokal `http://127.0.0.1:8080/` öffnen, während der Tunnel läuft. Der Port auf
dem eigenen Rechner muss frei sein. Für den regulären externen Erfassungsworker
weiterhin die öffentliche HTTPS-Adresse einrichten.

### 9. Erfassungsworker verbinden und Analysebetrieb einschalten

Auf der Weboberfläche mit deinem Konto anmelden. Unter **API-Schlüssel** einen
Schlüssel für den Erfassungsworker und das Projekt `viano-core` erstellen.
Den Schlüssel im Environment des **wowdiag-Workers** als `VBA_INTAKE_TOKEN`
hinterlegen. Dessen `[buganalysis]`-Abschnitt mit URL, Projekt und Profil einrichten
und bewusst aktivieren. Anleitung und Vorlagen:
[Erfassungsworker v0.4](deploy/capture-worker/README.md).

Der Erfassungsworker ist ein eigener Dienst auf dem Erfassungssystem. Er wird
nicht durch den BugAnalysis-Installer installiert oder gestartet. Die Datenbank-
Zugänge dieser beiden Programme sind ebenfalls voneinander unabhängig.

Anschließend den Analyseworker aktivieren:

```sh
sudo systemctl enable --now viano-bug-analysis-worker.service
sudo systemctl status viano-bug-analysis-api.service viano-bug-analysis-worker.service
```

**Ab diesem Zeitpunkt können vorhandene und neue Inbox-Aufträge kostenpflichtige
Modellaufrufe auslösen.** Mit einem kontrollierten echten Auftrag beginnen. In der
Weboberfläche Annahme und Fortschritt verfolgen, gegebenenfalls Testanfragen
beantworten und unter **Bearbeitete Fälle** das Ergebnis herunterladen.
Ergebnisse gehen in die Outbox, gescheiterte Analysen ins Review; blockierte Fälle
bleiben zur Fortsetzung erhalten. Ein Download bestätigt keine fachliche Übergabe.

### 10. Betrieb, Sicherung und Updates

```sh
sudo journalctl -u viano-bug-analysis-api -u viano-bug-analysis-worker -f
sudo systemctl stop viano-bug-analysis-worker.service
```

Der Worker beendet beim Stoppen den aktuellen Dispatch kontrolliert. Das kann
während einer laufenden Anfrage dauern. Vor Code-/Profiländerungen anhalten;
Konfigurationsbindungen laufender Fälle nicht beiläufig ändern.

Mindestens `/etc/viano-bug-analysis` und `/var/lib/viano-bug-analysis` gesichert
aufbewahren. Dazu zählen die Nutzer-SQLite sowie Integrationsschlüssel-SQLite und
deren separate Serverschlüsseldatei unter `runtime/integration-secrets`. Dieses
Verzeichnis ist kein beliebig löschbarer Cache. Für eine einfache konsistente
Dateisicherung beide Dienste anhalten. Zugriffe auf Backups mit Secrets schützen.

Für reguläre Codeupdates steht ein Update-Skript bereit:

```sh
sudo python3 /opt/viano-bug-analysis/deploy/update.py
```

Eine Vorschau ohne Netzwerkzugriff oder Änderungen ist mit `--dry-run` möglich.
Das Skript benötigt root und einen sauberen, root-eigenen Checkout mit Tracking-Branch.
Es holt den Remote-Stand, prüft Fast-forward, stoppt zuerst den Worker kontrolliert
und danach die API, installiert das aktualisierte Paket in die vorhandene venv
und startet nur die zuvor aktiven Dienste. Deren Startprüfungen testen die
Bereitschaft ohne LLM-Aufruf. Vorher inaktive Dienste werden nicht aktiviert.
Auch bei identischem Commit wird das Paket erneut installiert, etwa nach einem
vorherigen manuellen Pull. Parallele Updates sind gesperrt.
Konfigurationen, Zugangsdaten, Fallakten, Apache, Source-Checkout und Capture-Worker
werden nicht verändert. Das Skript erstellt keine Datensicherung und führt keine
projektspezifischen Migrationen aus.

Scheitert Installation oder Dienststart, bleiben beide Dienste gestoppt. Es gibt
keinen automatischen Rollback von Code oder Daten. Nach Behebung der Ursache das
Paket erneut installieren (auch mit diesem Skript möglich) und die gewünschten
Dienste ausdrücklich starten. Falls das Skript im bisherigen Checkout noch fehlt,
einmal vorab den folgenden Befehl ausführen und danach das Skript starten:

```sh
sudo git -C /opt/viano-bug-analysis pull --ff-only
```

Releasehinweise und geänderte Konfigurations-/Unit-Vorlagen vorher prüfen.
Das Updatebeispiel ersetzt keine gezielte Übernahme geänderter systemd-Units
mit anschließendem `systemctl daemon-reload`. Vorlagen werden vom Installer
absichtlich nicht über bestehende Konfigurationen kopiert.

Die Einrichtung ist abgeschlossen, wenn Anmeldung, automatischer Auftragseingang,
Analyse, Ergebnisdownload, menschliche Rückfrage und Wiederanlauf nach einem
Dienst-/Serverneustart geprüft wurden. Die native Linux-/HTTPS-Prüfung erfolgt auf
deinem Zielserver; lokale Windows-Entwicklungstests ersetzen sie nicht.

### Häufige Probleme bei der Ersteinrichtung

| Meldung / Verhalten | Zuerst prüfen |
| --- | --- |
| Installer verlangt root-eigenen Checkout | Pfad `/opt/viano-bug-analysis`, Eigentümer und Schreibrechte des Codes |
| `DEPLOY_MACHINE_CREDENTIALS` | Unbenutzten `[[clients]]`-Beispielblock entfernen oder dessen env-Token korrekt einrichten |
| `LLM_CREDENTIALS` | `worker.env`, Name der Schlüsselvariable in `llm.toml` und Laden der Datei durch systemd |
| `PROJECT_DATABASE_UNAVAILABLE` | DB-Adresse/Port, Netzwerkweg, Passwort und DB-Benutzer |
| Sourceprüfung schlägt fehl | Lokaler Checkout, tatsächlicher Commit, Leserechte und `/etc/viano-bug-analysis/gitconfig` |
| `nginx -t` meldet fehlendes Zertifikat | Zertifikat bereitstellen und die Beispielpfade im Site-Block ersetzen |
| Anmeldung funktioniert, aber kein Fall wird analysiert | Analyseworker läuft, Projektbindung stimmt, Auftrag ist tatsächlich angenommen |

Dienstfehler über `journalctl` prüfen. Ein fehlgeschlagener Start wird durch
systemd erneut versucht; nach einer Korrektur lässt sich der betreffende Dienst
mit `sudo systemctl restart DIENSTNAME` gezielt neu starten. Dabei den echten
Namen `viano-bug-analysis-api.service` beziehungsweise
`viano-bug-analysis-worker.service` einsetzen.

## Weiterführende Anleitungen

- [Verwendung und Funktionsweise](docs/user-guide.md) – auch im Webreiter Benutzeranleitung.
- [Projekt-, Source-, DB- und Modellkonfiguration](docs/project-configuration.md).
- [Übergabe-API und Rückgaben](docs/intake-api.md).
- [Analyseworker](docs/analysis-worker.md).
- [Benutzerkonten](docs/user-accounts.md).
- [Integrationsschlüssel](docs/integration-keys.md).
- [Linux-Betrieb im Detail](docs/linux-deployment.md).

## Entwicklung und technische Dokumentation

Project-independent foundations for reading, validating and extending ZIP case
packages. The authoritative design is [docs/architecture.md](docs/architecture.md).
The implemented v1 contract is documented in
[docs/package-format-v1.md](docs/package-format-v1.md).
Job state, checkpoints and inbox admission are documented in
[docs/lifecycle-v1.md](docs/lifecycle-v1.md).
Generic case construction and its input contracts are documented in
[docs/case-builder-v1.md](docs/case-builder-v1.md).
Vcore imports for wowdiag/wowsrc are documented in
[docs/vcore-adapters-v1.md](docs/vcore-adapters-v1.md).
Authenticated submission of new cases and completed-case feedback is documented in
[docs/intake-api.md](docs/intake-api.md). The HTTP API creates and queues packages;
external callers do not need to implement the internal package format.
The [continuous analysis worker](docs/analysis-worker.md) consumes that inbox,
routes cases to configured projects and resumes checkpointed analysis after restart.
The [web console](docs/web-console.md) shows active workers, case progress and token
charts, with corrections accounted for separately, and accepts new/return submissions.
The [Linux deployment guide](docs/linux-deployment.md) covers systemd services,
protected credentials, HTTPS and non-billable readiness checks.
The [integration key manager](docs/integration-keys.md) lets signed-in users
create, reveal and revoke project-scoped machine credentials.
The web tab **Benutzeranleitung** includes the [user guide](docs/user-guide.md)
and operator documentation, including project/source/database configuration.
After editing bundled documentation, run `python scripts/build_user_manual.py`.

Requires Python 3.11 or newer.

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
.\.venv\Scripts\python.exe -m pytest
```

The lifecycle foundation supports one-pass inbox processing, resumable package
checkpoints and a deterministic generic CaseBuilder. An async LLM gateway and CaseInterpreter
provide interpretation and bounded initial hypothesis generation, with durable
per-hypothesis budget accounting. An LLM-driven investigation controller connects
read-only queries, durable evidence and asynchronous test handoffs. Final evaluation
produces traceable diagnoses or human review. Confirmed diagnoses can produce
policy-bound Change Requests, with final output validation and atomic local
outbox/review publication. Operational telemetry observes the APIs and continuous worker.

A bounded single-case command-line trial now connects import, analysis and local
delivery with telemetry: [first real LLM trial](docs/first-llm-trial.md).
Use `python -m viano_bug_analysis.trial --help`. Only its `run` command makes LLM
requests; `prepare` and `check` do not contact model services.
For a new revision, `run --planning-mode joint` opts into a single interpretation/
hypothesis call with independent block validation: [joint case planning](docs/joint-case-planning.md).
New joint revisions use [v2 source constraints and dependency-aware corrections](docs/joint-case-planning-v2.md); frozen v1 cases remain replayable.

The trial enables bounded, durable early model-output corrections with explicit
validation feedback: [early correction](docs/early-correction-v1.md), configured
through [correction.example.toml](config/correction.example.toml).

Expected-behavior resolution and the read-only provider contract: [expected-behavior-v1.md](docs/expected-behavior-v1.md).

Configurable LLM transport, failover and durable retries: [llm-gateway-v1.md](docs/llm-gateway-v1.md), with [example configuration](config/llm.example.toml).

Gemini stable case caching, implicit cache measurements and
separate token/storage cost accounting: [context caching](docs/llm-context-caching.md),
with [native Gemini example](config/llm.gemini-cache.example.toml).
Lossless stable/live partition, versioned aliases and offline measurements:
[stable case cache](docs/stable-case-cache-v1.md).

Causal evidence direction, auditable confidence calibration and current-head
validation performance: [confidence and local performance](docs/causal-confidence-and-local-performance.md).

The first domain LLM phase and its source-reference contracts: [case-interpretation-v1.md](docs/case-interpretation-v1.md).

Initial hypotheses, revision-wide creation limits and equal budget allocations: [hypothesis-builder-v1.md](docs/hypothesis-builder-v1.md), with [analysis configuration](config/analysis.example.toml).

Durable investigation budget accounting, configurable costs/rewards and stopping
rules: [budget-manager-v1.md](docs/budget-manager-v1.md), with [budget configuration](config/budget.example.toml).

Case-local asynchronous test requests, confirmed feedback and budget-preserving
event-driven resume: [async-tests-v1.md](docs/async-tests-v1.md). Human test requests
can be answered through the web console; external bot adapters are separate integrations.

Read-only packaged source/database queries and the strict tool allowlist:
[investigation-tools-v1.md](docs/investigation-tools-v1.md).

Shared read-only Git/source/schema and MariaDB research, deterministic case
enrichment, bounded investigation prompts and the isolated World test database:
[project-research-v1.md](docs/project-research-v1.md), with
[project configuration](config/project.example.toml).

Portable evidence records, provenance, case-wide IDs and novelty-aware budget
integration: [evidence-store-v1.md](docs/evidence-store-v1.md).

Resumable, bounded LLM investigation cycles and their controller contracts:
[investigation-loop-v1.md](docs/investigation-loop-v1.md), with
[investigation configuration](config/investigation.example.toml).

Final hypothesis evaluation, traceable diagnoses and controlled human review:
[diagnosis-builder-v1.md](docs/diagnosis-builder-v1.md), with
[diagnosis configuration](config/diagnosis.example.toml).

Policy-bound coding requests and validated, resumable local output delivery:
[change-request-v1.md](docs/change-request-v1.md), with
[change request configuration](config/change-request.example.toml).

Opt-in operational logs, safe error chains, metrics, heartbeat/progress and passive
queue diagnostics: [telemetry-v1.md](docs/telemetry-v1.md), with
[telemetry configuration](config/telemetry.example.toml).

Schlanke Untersuchungsstarts mit gemeinsamer Erstbewertung: [Ablauf und Konfiguration](docs/investigation-startup-batch-v1.md).