Uebergabehinweise fuer den Frontend-Agenten (#531)

Der C#-Teil des Instanzmanagers ist fertig; was fehlt, ist die
Oberflaeche. Abschnitt 11 im Konzeptpapier ist die Uebergabe dafuer: der
Auftrag in einem Satz, die harte Grenze (keine .cs-Datei, git status darf
nur wwwroot zeigen), die vollstaendige API mit den Antwortcodes, die eine
eigene Behandlung verdienen, eine Reihenfolge, zwei Fallen und die drei
Punkte, die ausdruecklich liegen bleiben, weil sie C# sind.

Der WebUI-Leitfaden war an vier Stellen ueberholt und haette den naechsten
Agenten in die Irre geschickt: wwwroot liegt nicht mehr in
ClawdDotNet.Web, die Oberflaeche laeuft nicht mehr im Prozess der Instanz,
Port und Token stehen in manager.json statt in InstanceSettings.json, und
es gibt nicht mehr ein /api fuer eine Instanz. Ein Korrekturblock steht
jetzt vorweg und verweist auf Abschnitt 11; der Rest des Leitfadens - kein
innerHTML, kein Paketmanager, Token nur im sessionStorage, Farben aus
app.css - gilt unveraendert.

Die Arbeit selbst ist #531 und steht auf der Roadmap. Was nur in einer
Datei steht, ist keine eingeplante Arbeit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/Instanzmanager-Konzept.md

@@ -695,3 +695,143 @@ Hochfahren hinterlegte, stillschweigend ein anderer Test als beabsichtigt — de
 sagt eine Antwort „diese Instanz läuft bereits", er übernimmt sie, und der Starter wird nie
 angefasst. Das ist mir dreimal passiert. Der falsche Socket hängt jetzt am falschen
 Starter: Er antwortet nur, wenn wirklich ein Prozess läuft.
+
+---
+
+## 11 — Übergabe an den Frontend-Agenten
+
+Stand 2026-09-09. Der C#-Teil des Instanzmanagers ist fertig; was fehlt, ist die
+Oberfläche. Dieser Abschnitt ist die Übergabe dafür.
+
+### 11.1 Der Auftrag, in einem Satz
+
+**Bringe der Weboberfläche bei, dass es mehrere Instanzen gibt** — Vorhaben **#531**,
+alles in `src/ClawdDotNet.Manager.Web/wwwroot/`.
+
+Heute spricht sie `/api/…` an und bekommt die eine laufende Instanz. Laufen zwei,
+antwortet der Manager mit **HTTP 409** und der Bitte, die Kopfzeile `X-Instanz` zu setzen.
+Dann ist die Oberfläche unbedienbar — und das ist der einzige Punkt, der den
+Mehrinstanzbetrieb im Browser noch aufhält.
+
+### 11.2 Die Grenze, und sie ist hart
+
+| Nicht anfassen | Warum |
+|---|---|
+| **Jede `.cs`-Datei, überall** | Dahinter stehen Prozessaufsicht, Lizenz, Token und die Weiterleitung. Ein Fehler dort beendet Instanzen oder lässt einen Absturz unbemerkt |
+| `*.csproj`, `ClawdDotNet.slnx`, `deploy/`, `NuGet.Config` | Bauplan und Release-Strecke |
+| `docs/Roadmap.md` zwischen den `<!-- dc:roadmap -->`-Markern | Erzeugte Kopie |
+
+**Ein Griff nach C# ist kein Regelverstoß, sondern ein Befund:** Er heißt, dass die API
+etwas nicht hergibt, was sie hergeben müsste. Dann melden (`dc_report`, Projekt
+`clawddotnet`) und an der Oberfläche weiterbauen — nicht selbst in den Kern greifen.
+
+Zur Kontrolle vor jeder Abgabe: `git status` darf **ausschließlich** Dateien unter
+`src/ClawdDotNet.Manager.Web/wwwroot/` zeigen.
+
+### 11.3 Was sich seit dem WebUI-Leitfaden geändert hat
+
+Der [WebUI-Leitfaden](WebUI-Leitfaden.md) gilt weiter für Stil, Sicherheit und Aufbau der
+Oberfläche. Vier Dinge darin sind überholt:
+
+| Damals | Heute |
+|---|---|
+| `wwwroot` liegt in `src/ClawdDotNet.Web/` | **`src/ClawdDotNet.Manager.Web/`** |
+| Die Oberfläche läuft im Prozess der Instanz | Sie läuft im **Instanzmanager**, einem eigenen Prozess |
+| `http://127.0.0.1:7001`, Token in `InstanceSettings.json` | **`webUiPort` und `webUiToken` in `manager.json`** (Vorgabe 7000) |
+| Eine Instanz, ein `/api` | **N Instanzen**, der Manager leitet weiter |
+
+Der Rest des Leitfadens — kein `innerHTML`, kein Paketmanager, Token nur im
+`sessionStorage`, Farben aus `app.css` — gilt unverändert.
+
+### 11.4 Die API, gegen die du baust
+
+**Was den Manager selbst angeht** (wird *nicht* weitergeleitet):
+
+| Aufruf | Was er tut |
+|---|---|
+| `GET /api/verwaltung/instanzen` | Liste: `{ id, name, zustand, prozess, autostart }` |
+| `POST /api/verwaltung/instanzen` `{ "name": "…" }` | Legt eine an |
+| `POST /api/verwaltung/instanzen/{id}/start` | Startet sie |
+| `POST /api/verwaltung/instanzen/{id}/stop` | Hält sie an |
+| `POST /api/verwaltung/instanzen/{id}/fenster` | Holt ihr Desktop-Fenster nach vorn |
+
+`id` ist der Ordnername (`Instance-Test`). `zustand` ist einer von `Unknown`, `Stopped`,
+`Running`, `Silent`, `Crashed`.
+
+**Alles andere unter `/api`** geht unverändert an eine Instanz — `/api/info`,
+`/api/agents`, `/api/chat`, `/api/jobs`, `/api/tasks`, `/api/staging`, `/api/usage`,
+`/api/logs/modules`. Die Übertragungstypen sind dieselben wie bisher; hier ändert sich
+nichts außer der Adressierung.
+
+**Welche Instanz gemeint ist**, sagt die Kopfzeile `X-Instanz` mit der `id`. Fehlt sie:
+Läuft genau eine, ist sie gemeint. Laufen mehrere, kommt **409** mit einem erklärenden
+Text — dann muss die Oberfläche eine wählen lassen. Läuft keine, ebenfalls 409.
+
+**Der Ereignisstrom** (`/events`, `/events/logs`) führt alle laufenden Instanzen zusammen.
+Jedes Ereignis hat **zusätzlich** `instanz` (die `id`) und `instanzName`. Die bisherigen
+Felder bleiben unverändert — vorhandene Ansichten funktionieren weiter, sie wissen nur
+noch nicht, von wem etwas kommt.
+
+**Antwortcodes, die eine eigene Behandlung verdienen:**
+
+| Code | Bedeutung |
+|---|---|
+| 401 | Token fehlt oder taugt nicht → zurück zur Anmeldung (gibt es schon) |
+| **402** | Ohne gültige Lizenz startet keine Instanz |
+| **409** | Unklar, welche Instanz gemeint ist — oder eine Aktion passt nicht zum Zustand |
+| **502** | Die Instanz antwortet nicht. **Kein Fehler des Managers** — sag das auch so |
+
+### 11.5 Reihenfolge
+
+1. **`X-Instanz` mitschicken.** In `modules/api.js` gibt es genau eine Stelle, an der
+   `fetch` aufgerufen wird — dort die Kopfzeile aus einer gewählten Instanz setzen. Beim
+   Ereignisstrom geht das nicht (`EventSource` kann keine Kopfzeilen); dort ist es auch
+   nicht nötig, der Manager führt ohnehin alle zusammen.
+2. **Instanzauswahl im Rahmen.** Eine Liste aus `/api/verwaltung/instanzen`, die gewählte
+   Instanz im `sessionStorage` neben dem Token. Zustand sichtbar machen — `Silent` und
+   `Crashed` sind keine Nebensache, sondern der Grund, warum es den Manager gibt.
+3. **Verwaltungsansicht.** Anlegen, starten, anhalten, Fenster nach vorn. Die Liste nach
+   jeder Aktion neu holen; die Zustände ändern sich im Hintergrund.
+4. **Herkunft der Ereignisse zeigen.** `instanzName` an Chat-, Schritt- und
+   Protokollzeilen, damit in einem Fenster mit drei Instanzen erkennbar ist, wer spricht.
+
+### 11.6 Zwei Fallen
+
+**Der Zustand ändert sich, ohne dass jemand klickt.** Der Manager sieht alle paar Sekunden
+nach; eine Instanz kann abstürzen oder verstummen, während die Liste offen steht. Eine
+Ansicht, die nur beim Öffnen lädt, zeigt dann etwas Falsches — und zwar genau in dem
+Moment, für den es diese Ansicht gibt.
+
+**Der Manager beendet beim Schließen keine Instanz.** Wer die Weboberfläche zumacht oder
+den Manager beendet, beendet nichts. Was läuft, läuft weiter, und der nächste Manager
+findet es wieder. Eine Oberfläche, die „Manager beenden" mit „alles beenden" beschriftet,
+sagt die Unwahrheit.
+
+### 11.7 Wie du es ausprobierst
+
+```bash
+dotnet build
+```
+
+`manager.json` liegt unter `%APPDATA%\ClawdDotNet\` (Windows) beziehungsweise
+`~/.config/ClawdDotNet/`; ein anderer Ort geht über `--config <Verzeichnis>`. Nötig sind
+mindestens `webUiToken` (≥ 20 Zeichen) und `instanceExecutable`, wenn Manager und Instanz
+nicht im selben Ausgabeordner liegen.
+
+```bash
+dotnet run --project src/ClawdDotNet.ManagerApp
+```
+
+Der Manager schreibt seine Adresse auf die Standardausgabe und protokolliert nach
+`<Datenverzeichnis>/Logs/Manager/`. Zum Prüfen mit zwei Instanzen: eine zweite über
+`POST /api/verwaltung/instanzen` anlegen, beide starten — dann muss die Oberfläche eine
+wählen lassen.
+
+### 11.8 Was ausdrücklich liegen bleibt
+
+Diese drei Punkte sind **C#** und warten auf den Kern-Agenten. Nicht anfangen:
+
+1. **`webServerPort` aus der Instanz entfernen.** Erst sinnvoll, wenn 11.5 steht.
+2. **Lizenzprüfung aus der Instanz nehmen** (E-M3 vollständig). Braucht vorher einen
+   Handschlag, an dem eine Instanz erkennt, ob ein Manager da ist.
+3. **Verstummte Instanzen neu starten?** Nicht entschieden — siehe Abschnitt 7.

docs/WebUI-Leitfaden.md

@@ -8,7 +8,27 @@ Gegenstück zum [Oberflächen-Leitfaden](Oberflaechen-Leitfaden.md), der für
 Avalonia gilt.
 
 Vorhaben im Deploymentcenter:
-**#494** (Weboberfläche), **#493** (Fachlogik nach `App`).
+**#494** (Weboberfläche), **#493** (Fachlogik nach `App`), **#531** (Instanzen in der
+Oberfläche).
+
+---
+
+## Vorweg: Vier Dinge in diesem Leitfaden sind überholt
+
+Seit dem 2026-09-09 trägt der **Instanzmanager** die Weboberfläche (#528). Der Leitfaden
+gilt weiter für Stil, Sicherheit und Aufbau — kein `innerHTML`, kein Paketmanager, Token
+nur im `sessionStorage`, Farben aus `app.css`. Vier Angaben darin stimmen nicht mehr:
+
+| Im Text | Tatsächlich |
+|---|---|
+| `wwwroot` liegt in `src/ClawdDotNet.Web/` | **`src/ClawdDotNet.Manager.Web/wwwroot/`** |
+| Die Oberfläche läuft im Prozess der Instanz | Sie läuft im **Instanzmanager**, einem eigenen Prozess. Er spricht mit den Instanzen über einen Socket und **leitet weiter** |
+| `http://127.0.0.1:7001`, Einstellungen in `InstanceSettings.json` | **`webUiPort`, `webUiBinding`, `webUiToken` in `manager.json`**, Vorgabe 7000 |
+| Ein `/api` für eine Instanz | **N Instanzen.** `/api/verwaltung/…` gehört dem Manager, alles andere unter `/api` geht an die Instanz aus der Kopfzeile `X-Instanz` |
+
+**Der aktuelle Auftrag und die vollständige API stehen in**
+[Instanzmanager-Konzept.md, Abschnitt 11](Instanzmanager-Konzept.md#11--übergabe-an-den-frontend-agenten).
+Lies den zuerst; dieser Leitfaden ist das Nachschlagewerk daneben.
 
 ---