# Inbetriebnahme: von „Container läuft" zu „Anlage arbeitet"

**Einordnung:** JanuaPort ist KI-native Automatisierung. Die KI des Kunden baut Abläufe gemeinsam mit dem Menschen (Kartei als Arbeitsliste, Use-Case-Katalog, Wissen); Skripte und RPA docken mit eigenem Token an; JanuaPort setzt Rechte, Freigaben und Protokoll durch. JanuaPort funktioniert mit n8n als sichere Werkzeug-Schicht, setzt n8n aber nicht voraus. JanuaPort ist seit Oktober 2026 allgemein verfügbar und wird von zahlenden Kunden eingesetzt.

**Für wen:** den Admin einer frischen JanuaPort-Anlage — egal, auf welchem Weg sie
entstanden ist. Die drei Provisionierungs-Wege enden alle am selben Punkt (ein
laufender Container mit leerer Anlage) und setzen hier fort:

| Weg bis „Container läuft" | Anleitung |
|---|---|
| VM mit Infrastruktur-Automatik (Hetzner-Referenz) | [`docs/deploy-hetzner.md`](deploy-hetzner.md) |
| Selbst-Hoster (`docker compose up`) | [`docs/installation.md`](installation.md) — vom Download zum laufenden Container |
| JanuaPort Box | `docs/box-runbook.md` |

**Woher dieses Dokument kommt:** Es ist das Protokoll eines echten, vollständigen
Neuaufbaus (Showcase-Anlage, 12./13.08.2026), MCP-first gefahren — jeder Schritt,
jeder Stolperstein und jede bewusste Mensch-Ausnahme stammen aus diesem Lauf, nicht
vom Schreibtisch. Wo der Admin-MCP etwas (noch) nicht kann, steht es hier ehrlich
mit Issue-Nummer.

## 0. Das Betriebsmodell in drei Sätzen

Ein **Admin-Agent** (z. B. Claude mit dem Admin-MCP verbunden) kann die gesamte
Einrichtung fahren — Integrationen, Teams, Berechtigungen, Pseudonymisierung,
Token, Diagnose. **Genau zwei Dinge bleiben bewusst beim Menschen:** der
allererste Admin-Zugang (Passwort + erster Admin-Token) und **jeder
Geheimnis-Wert** (API-Schlüssel, Client-Secrets — sie laufen nie durch einen
Chat). Drittens gilt: Tenant-Administration bei Fremdanbietern (Entra, Exchange)
bleibt ebenfalls Mensch-Arbeit — das Werkzeug bereitet maximal vor (fertige
Skripte, exakte Klick-Wege).

## Team-Token direkt in den Vault (Stufe 1, gebaut/unveröffentlicht)

Ein Betreiber kann auf dem Host einen Team-Token ausstellen und direkt als
Credential speichern. Das Team braucht einen freien Token-Vorratsplatz,
ausreichende Rechte und einen freien Lizenzplatz:

```sh
docker exec jnpt-jnpt-1 /jnpt team-token create \
  --team <name|id> --label <label> --allow <integration>:<tool> \
  | docker exec -i jnpt-jnpt-1 /jnpt credential set --name <credential>
```

`--team` muss genau einen Namen oder eine ID treffen; eine Namens-/ID-Kollision
wird abgewiesen. `--label` und mindestens ein `--allow` sind Pflicht.
`--allow` ist wiederholbar, immer werkzeuggenau und ohne Wildcards; optional
setzt `--expires <RFC3339>` einen Ablauf. Ohne das Flag gibt es keinen Ablauf.
Die CLI prüft dieselben Domänenregeln wie REST über `teamtoken.Service.Issue`.
Sie lädt den Offline-Katalog; außerhalb bekannter Werkzeuge müssen Teamrechte
wörtlich passen. Die Laufzeit kappt weiterhin an den aktuellen Teamrechten.

Der Befehl verweigert die Ausgabe, wenn stdout erkennbar ein Terminal ist
(Abbruch **vor Token und Audit**). Über `docker exec` ohne `-t` ist das nicht
erkennbar; deshalb immer direkt in `credential set` pipen. stdout im Container
ist dann immer eine Pipe; ohne die Weiterleitung landet der Klartext im Host-Terminal.
Der Klartext steht genau einmal, ohne Zeilenumbruch oder Zusatz, auf stdout.
Token-ID, Team, Label, Scopes und Ablauf stehen auf stderr. Deshalb kein
`2>&1` und kein `docker exec -t` für diese Pipe verwenden.
Das Audit trägt `via: cli` ohne Personen-Akteur und ohne Secret. Scheitert die
Pflichtabsicht, entsteht kein Token. Scheitert das Ergebnis-Audit, wird vor der
Ausgabe ein Widerruf versucht und kein Erfolg gemeldet. Der Widerruf bei einem
Schreibfehler geschieht nur nach bestem Bemühen: Ein Docker-Stream sieht meist
keinen Fehler, eine native Pipe beendet Go bei gebrochener Pipe per SIGPIPE
vor dem Widerruf. Bei erfolgreichem Widerruf bleibt die angelegte Zeile als
widerrufen sichtbar.

Dies ist ein Betreiber-Geheimnisweg: kein neues Admin-MCP-Pendant und keine
neue REST-Route. `credential set` bleibt unverändert. Die beiden Prozesse
bilden keine gemeinsame Transaktion: Scheitert `credential set`,
den ausgestellten Token anhand der ID auf stderr mit `jnpt token revoke <id>`
widerrufen. In Bash macht `set -o pipefail` Fehler beider Prozesse sichtbar.

## 1. Erstzugang (Host-Schritte)

**Betreiber-Mail einschalten (Stufe 1, gebaut):** Den vorhandenen
SMTP- oder Graph-Weg einrichten, Empfänger in `JNPT_SMTP_TO` angeben und
`JNPT_NOTIFY_STATE=true` setzen; Anleitung in [Update-Runbook, Benachrichtigung](update-runbook.md).
Die Familien sind Update, Zustand (Lizenz/Plätze/Erreichbarkeit),
Credential-Ablauf und `admin_mcp_change`. Letztere meldet Admin-KI-Änderungen
an Pins, Repo-URL, Credential-Override sowie Anlage/Anhebung mit Adressen oder
Instanzwerten (nur Feldnamen/Hosts, keine Werte), Team-Integrationsstufen sowie
Protokolltiefe/Inhaltsfrist (alt → neu); dazu menschliche Änderungen
der Admin-MCP-Schalter. Versand ist best effort; fehlende Mail hält kein Setup an.
Zehn Mails je Stunde und Prozess, danach Sammelmail, Schalter ungebremst.
Der Zähler und wartende Sammelvorgänge sind flüchtig und gehen beim Neustart
verloren; das Protokoll bleibt vollständig. Ohne eingeschalteten Mail-Weg
warnt die Seite Admin-MCP-Berechtigungen sichtbar. Details und Grenzen:
[Setup-Modus und Mail](admin-mcp.md#mail-an-den-betreiber-1084-b-stufe-1-gebaut).

0. **Master-Schlüssel sichern — VOR allem anderen.** Läuft die Anlage ohne
   gesetztes `JNPT_MASTER_KEY`, erzeugt sie beim allerersten Start ihren
   Master-Schlüssel selbst und schreibt ihn **einmalig** in die Startausgabe
   (`docker logs jnpt-jnpt-1`, ganz oben — ein umrahmter Kasten mit Pfad,
   Wert und Aufforderung). Diesen Wert **jetzt** in den Passwort-Manager des
   Betriebs kopieren, getrennt von den Backups.
   ⚠️ **Er erscheint nur dieses eine Mal.** Ohne ihn sind nach einem Verlust des
   Volumes alle Credentials, alle Pseudonym-Zuordnungen und alle Backups
   unlesbar — es gibt keinen Reset und keinen Support-Weg
   (`docs/disaster-recovery.md` §0). Verpasst? Der Wert steht in der Key-Datei.
   Das Image hat keine Shell und kein `cat`; lesen Sie die Datei deshalb über
   `docker cp` aus, ohne Kopie auf der Platte:
   `docker cp jnpt-jnpt-1:/data/jnpt.key - | tar -xO`.
   Der Leitstand zeigt die Aufforderung als Karte **„Master-Schlüssel"**, bis
   dort **„Ist verwahrt"** bestätigt wird; danach ist sie dauerhaft weg. Den
   Wert zeigt die Oberfläche nie, und die Key-Datei gibt es dort bewusst nicht
   zum Herunterladen.
1. **Admin-Passwort setzen:** Die GUI verlangt beim ersten Aufruf einen
   Setup-Schritt (min. 12 Zeichen). Die Verwaltungsfläche ist nie öffentlich —
   erreichbar nur über Tailnet, internes Netz oder einen SSH-Tunnel.
2. **Ersten Admin-Token erzeugen** (CLI auf dem Host):
   `docker exec jnpt-jnpt-1 /jnpt admin-token create --label <zweck> --expires 720h`
   Der Wert erscheint genau einmal. Das Ablaufdatum ist Pflicht (höchstens
   1 Jahr); vor Ablauf einen neuen Token anlegen.
3. **Admin-Agent verbinden:** MCP-Endpunkt `…/admin/mcp`, Bearer = Admin-Token.

> Die saubere Reihenfolge ist Passwort **vor** Token. Nichts erzwingt sie —
> aber der Token gehört einem Betreiber, dessen GUI-Zugang schon steht.

4. **Basis-Einrichtung prüfen** (GUI: *Credentials* → Sektion
   „Basis-Einrichtung (System)"): Dort steht jede Stelle, die JanuaPort für sich
   selbst braucht — **auch die, die noch fehlt**. Auf einer frischen Anlage ist
   das mindestens der **Lizenz-Abruf** (`lizenz-abruf`, Zweck „Lizenz-Abruf beim
   Hersteller"): Er ist dauerhaft reserviert und trägt die Zeile
   **„fehlt"**, bis das Abruf-Secret hinterlegt ist. Über „Anlegen" ist der Name
   vorbelegt und gesperrt — er muss nicht abgetippt werden (ein Tippfehler legte
   sonst still ein Integrations-Credential an). Der Abruf selbst wird über
   *Lizenz → Abruf einrichten* eingerichtet (`docs/license.md`); solange er
   fehlt, geht die Lizenz nur über den Datei-Weg.
   Kommt SSO dazu (§3), erscheint dort zusätzlich die **Verzeichnis-Suche** —
   auch sie zuerst als „fehlt".
   Fährt die Anlage einen **Anbindungsweg** (ChatGPT über den OpenAI-Tunnel —
   erkennbar am eingehängten Bereitstellungs-Verzeichnis
   `/run/jnpt/tunnel`, das die ausgelieferten Compose-Dateien standardmäßig
   mitbringen), steht dort als dritte Stelle
   **`openai-tunnel`** („Anbindungsweg ChatGPT — Laufzeit-Schlüssel des
   OpenAI-Tunnels"). Fehlt der Mount (und ist auch `JNPT_TUNNEL_KEY_FILE` nicht
   gesetzt, das nur noch den Ort überschreibt), erscheint die Zeile
   gar nicht — wer keinen Anbindungsweg fährt, merkt von diesem Teil nichts.
   Sobald der Wert hinterlegt ist, stellt ihn das Gateway dem Beisteller
   innerhalb einer Minute bereit; Rotation läuft ab dann über dieselbe Zeile
   (Aufsetzen: `docs/deploy-hetzner.md` §13). ⚠️ Die Spalte **Ablauf** bleibt
   bei dieser Stelle leer — OpenAI-Laufzeitschlüssel laufen ohne Zutun nicht ab.
   Auf der Kommandozeile sagt dasselbe `docker exec jnpt-jnpt-1 /jnpt credential
   list`: unter der Tabelle steht je **fehlender** Stelle eine Zeile
   `FEHLT  <name>  <zweck>` (eine vorbereitete Stelle gilt als vorhanden).

> **Ritual, kein Kür:** Jeder Diagnose- oder Wegwerf-Token (z. B. zum
> Fehlersuchen) gehört sofort nach Gebrauch widerrufen —
> `docker exec … /jnpt admin-token revoke <id>` (`<id>` positional, aus der
> Ausgabe von `admin-token create`). Dafür gibt es bewusst keinen
> Admin-MCP-Weg: Admin-Tokens verwalten sich nicht selbst über MCP
> (kein Self-Escalation-Pfad).

## 2. Nutzer und Teams

1. **Nutzer anlegen** (`admin_create_user`) — eine organisatorische Identität,
   kein Login. ⚠️ **Bei SSO-Betrieb sofort die Entra-Objekt-ID verknüpfen**
   (`admin_set_user_external_subject`, der `oid`-Claim): Ohne Verknüpfung legt
   der erste SSO-Login ein **Duplikat** an (live passiert).
2. **Teams anlegen** (`admin_create_team`) — Slug bewusst wählen, er ist die
   Endpunkt-Adresse und **nicht änderbar**. Teams starten ohne alles
   (deny-by-default).
3. **Team-Endpunkte einschalten** (`admin_set_team_endpoint_view`) —
   `/mcp/v/<slug>` ist die kuratierte Sicht, über die Clients verbinden.

**Empfohlene Grundstellung (im Lauf bewährt):** Der Haupt-Endpunkt `/mcp` bleibt
leer; jede Integration wird ausschließlich über Team-Scopes an Team-Endpunkten
vergeben. Katalog, Problem-Melden und Ping sind strukturell immer da und brauchen
keinen Scope.

## 3. SSO (Entra) — wenn das Unternehmen ein Verzeichnis hat

Konfiguration: `.env` neben der Compose-Datei (`JNPT_SSO_*`, Runbook §11 —
die Compose-Datei selbst wird nicht editiert). Die Entra-Seite Schritt für
Schritt (App-Registrierung, Token-Version 2, App-ID-URIs, Rückruf-URIs,
Zuweisung) steht für den Mandanten-Admin in `docs/sso-entra-einrichtung.md`.
Danach im Portal und in der Anlage:

1. **App-ID-URIs**: je Endpunkt-Adresse ein Eintrag (`https://<host>/mcp` und
   jede Team-View). ⚠️ Die Liste ist **ersetzend** — ergänzen, nie überschreiben.
2. **App-Rollen** je Team anlegen und Nutzern zuweisen. Drei Stolpersteine aus
   dem Live-Lauf: Rolle muss **aktiviert** sein (App-Registrierung → App-Rollen →
   Zeile anklicken → Häkchen unten) · Mitgliedertyp **Benutzer/Gruppen** · die
   Zuweisen-Ansicht der Unternehmensanwendung **synchronisiert verzögert** —
   Panel schließen, „Aktualisieren" oben rechts, 2–3 Minuten Geduld. Eine Rolle
   je Zuweisungsvorgang.
   ⚠️ **Die App-Registrierung umbenennen statt neu anlegen:** Ein neuer Name
   geht über **Branding & Eigenschaften** der bestehenden App-Registrierung —
   **kein** Neuanlegen. Eine neue Registrierung hätte eine neue Client-ID,
   verlorenen Consent und ein neues Secret zur Folge, und Bestandsverbindungen
   müssten neu verbunden werden (Runbook §11.6.4). **Manifest-Warnung nicht
   überbewerten:** Entra markiert nur das **alte Azure-AD-Graph-Format** als
   abgekündigt — das manuelle Editieren des aktuellen Manifests (Punkt 1,
   Runbook §11.6.1) bleibt möglich und ist weiterhin der Weg.
3. **Rollen an Teams brücken** (`admin_set_team_idp_groups`, Rollenwert =
   Claim-Wert).
4. ⚠️ **Gruppen-Freigabe** (der bewusste Admin-Akt: „Berechtigung entsteht nie
   durch Login allein"): Jede Rolle/Gruppe, die sich anmelden darf, muss
   **freigegeben** sein — sonst scheitert der Login mit „Autorisierung
   fehlgeschlagen". Heute nur in der GUI (Team-Seite → Freigegebene Gruppen);
   über den Admin-MCP noch nicht möglich, geplant.
5. **Sockel-Berechtigung** (`JNPT_SSO_DEFAULT_SCOPE`): bekommt **jeder**
   erfolgreiche Login vor jeder Team-Zuordnung. Empfehlung: **leer lassen** —
   nie eine Integration. Das Gedächtnis (`memory_*`) braucht hier
   nichts mehr: Es ist ein Basis-Werkzeug und für jeden gültigen Zugang da
   (wie `ping`, `catalog`, `report_problem`). Ein alter `memory`-Eintrag wird
   weiterhin angenommen, ist aber wirkungslos und wird beim Start gemeldet.
6. **Client verbinden:** Beim Anlegen des Connectors in Claude gehört die
   **OAuth-Client-ID in die erweiterten Einstellungen** — ohne sie scheitert
   der Verbindungsaufbau.

**Stolpersteine beim Verbinden (Live-Lauf):**

- **404 ohne OAuth-Discovery** beim Verbinden auf eine **nicht eingeschaltete**
  Endpunkt-View → Claude meldet irreführend „Client-Registrierung nicht
  unterstützt" — das ist nicht das eigentliche Problem. Prüfen: Ist die View
  am Team überhaupt eingeschaltet (§2 Punkt 3)?
- **Ein aktiver View liefert nie 0 Tools.** Zeigt `tools/list` nach dem
  Verbinden eine leere Liste, ist die Verbindung selbst das Problem (trennen +
  neu verbinden), nicht die Scope-Vergabe — die hätte mindestens die
  strukturell immer vorhandenen Werkzeuge (Katalog, Problem-Melden, Ping)
  gezeigt.
- **Ein staler Browser-Tab täuscht fehlende Features vor.** Die Versionsanzeige
  der GUI kommt live von der API, `index.html` selbst ist `no-store` — ein
  hartnäckig altes Bild braucht meist nur **F5**, bevor man nach einem echten
  Fehler sucht.

## 4. Je Integration: die eiserne Reihenfolge

Immer in dieser Folge — Pseudonymisierung **vor** der ersten echten Nutzung,
Team-Freigabe **zuletzt**:

1. **Connector-Beschreibung einspielen** (YAML nach `JNPT_CONNECTORS_DIR`,
   Neustart — Datei+CLI, noch kein Admin-MCP-Weg; mitgelieferte Vorlagen kommen
   über den Katalog). Neustarts sind unkritisch: bestehende Client-Verbindungen
   überleben sie nachweislich.
2. **Credential vorbereiten** (`admin_prepare_credential` — nur der NAME).
   **Der Wert kommt vom Menschen** über die GUI (Wert und Ablaufdatum mit
   einem Speichern).
3. **Live-Verbindung belegen** (`admin_check_connector`; für
   Datenbank-Integrationen `admin_check_database` — vierstufig inkl.
   `SELECT 1`-Probe je Richtung): Spec · Credential · Probe gegen das echte
   System. Erst ein echter Erfolg zählt als „fertig".
4. **Pseudonymisierung konfigurieren:**
   - Feldnamen **belegen, nicht raten**: `admin_probe_tool_response_fields`
     (kostet einen echten API-Call; geht nur bei Werkzeugen ohne
     Pflichtparameter) oder die offizielle API-Doku. Ein Tippfehler im Feldnamen
     wirft keinen Fehler — die Zeile sieht nur geschützt aus.
   - ⚠️ **Schlüsselnamen können mehrdeutig sein** (Lexware: `name` = Kundenname
     im Kontakt, aber Artikelname in Rechnungspositionen). Voll-Ersetzung dann
     **tool-genau** setzen, nicht integrationsweit — oder den Muster-Scan nehmen,
     dessen Form-Prüfung Fehlgriffe verhindert.
   - Muster-Empfehlung für Geschäftsdaten: `iban`, `email`, `steuernummer`
     (harte Inhalts-Prüfung). `telefon`/`geburtsdatum` nur bewusst — Belege sind
     voller Nummern und Daten, und **Muster sind unumkehrbar**.
   - Werte in **Arrays von Zeichenketten** (z. B. `emailAddresses.business`)
     erreicht die Ersetzung **seit Version 0.26.0** — es zählt der Schlüssel, unter dem
     die Liste hängt, für `read` wie für `scan`. Bis dahin war das eine
     benannte Klartext-Lücke; wer eine Deklaration deswegen zurückgebaut hat,
     setzt sie jetzt neu (von selbst kommt sie nicht wieder).
5. **Team-Freigabe** (`admin_set_team_scopes`): ersetzt die **ganze** Liste —
   Bestehendes mitführen. Schreib-Werkzeuge immer tool-genau.
6. **Gegenprobe aus Nutzer-Sicht:** Verbindung des Teams öffnen, Werkzeug
   aufrufen, Kürzel sehen (`‹name-…›` — deterministisch: gleicher Wert, gleiches
   Kürzel). Scope-Änderungen erreichen laufende Verbindungen ohne Neu-Verbinden.
7. **Audit-Gegenprobe** (`admin_query_audit_log`): jeder Schritt mit Akteur,
   Geheimnis-Werte geschwärzt.

## 5. Sonderfall Microsoft-Postfach

Vollständig in [`docs/connector-microsoft-graph-mail.md`](connector-microsoft-graph-mail.md).
Die Lehren des Live-Laufs:

- **Ziel ist ein freigegebenes Postfach** (kostenlos), nie das persönliche
  Postfach eines Menschen.
- **Ohne Schritt 4 (Exchange-Grenze) darf die App JEDES Postfach lesen** — und
  nichts warnt. Der Live-Lauf hat genau diesen Zustand vorgefunden. Skript-Vorlage:
  [`examples/exchange-postfach-grenze.ps1`](../examples/exchange-postfach-grenze.ps1).
- **Entra- und Exchange-Rechte addieren sich:** Beim RBAC-Weg die mandantenweite
  `Mail.ReadWrite`-Zustimmung entfernen, sonst ist die Grenze wirkungslos. Der
  App-Token wird auch ohne Entra-Zustimmung ausgestellt (live belegt).
- **Zwei Cache-Fallen:** Exchange-Änderungen brauchen 30 Minuten bis 2 Stunden.
  Und die Anlage cacht den App-Token bis zu dessen Ablauf — nach
  Rechte-Änderungen einmal neu starten, sonst testet man den alten Stand.
- **Der Beweis braucht beide Richtungen:** erlaubtes Postfach → Erfolg, ein
  nachweislich **existierendes** fremdes Postfach → 403. Ein 404 beweist nichts.
  ⚠️ **Die Kontroll-Tabelle (`Test-ServicePrincipalAuthorization`) kann leer
  zurückkommen** — das ist für sich kein Fehlsignal. Der echte Werkzeug-Aufruf
  gegen das Postfach bleibt in jedem Fall der Beleg, nicht die Tabelle.
- **Mehrere Postfächer:** ein Postfach = eine App = ein Credential = eine
  Integrations-Instanz (`admin_create_integration`). Die Grenze erzwingt das
  Zielsystem je App; Parameter-Einengung in JanuaPort selbst ist geplant.

## 6. Betrieb: was der Admin regelmäßig tut

- **Sicherheitshinweise** zum Host lesen (`docs/sicherheitshinweise.md`): Lücken im Kernel oder in
  Docker schließt kein JanuaPort-Update, sondern der Betreiber am Host.
- **Problem-Meldungen** einsehen (`admin_list_problem_reports`) — Agenten melden
  über das eingebaute Werkzeug; Status und Admin-Notiz pflegen.
- **Lizenz-Stand** fragen (`admin_get_license`): Plätze und, falls die Anlage
  über ihrem Limit liegt, der Tag, ab dem die überzähligen gesperrt werden.
  Frische Anlage = **Free mit drei Plätzen, kein Ablauf** — der vierte
  Platz entsteht nicht. Details und der Weg, einen Platz freizugeben:
  `docs/license.md`.
- **Audit** stichprobenartig lesen; die Klartext-Gegenprobe („steht der echte
  Wert irgendwo?") gehört zu jeder neuen Integration.
- **Backup:** `docker compose exec jnpt /jnpt backup` zieht einen
  verschlüsselten Voll-Abzug (DB + nicht-geheimer `JNPT_*`-Stand) in **eine**
  Datei — läuft neben dem laufenden Gateway. Der Master-Key gehört
  **getrennt davon** aufbewahrt (Passwortmanager/Secret-Manager): Verlust macht
  den Tresor **und alle Backups** unwiederbringlich. Ablauf, Automatisierung
  und Restore-Drill: [`docs/disaster-recovery.md`](disaster-recovery.md).
- **Master-Schlüssel wechseln (Anlassfall, nicht Routine):** Wenn der Schlüssel
  in falsche Hände geraten sein könnte, wechselt ihn `jnpt key rotate` —
  **Einzelknoten**, in dieser Reihenfolge:

  ```bash
  docker compose down                      # 1) Gateway stoppen (nicht optional)
  docker compose run --rm jnpt key rotate  # 2) rotieren (--new-key/--new-key-file optional)
  #                                        # 3) Schlüsselquelle nachziehen:
  #    Key-DATEI  → hat der Befehl selbst aktualisiert
  #    JNPT_MASTER_KEY → JETZT auf den neuen Wert setzen, VOR dem Start
  docker compose up -d                     # 4) starten
  docker compose exec jnpt /jnpt backup    # 5) ohne Host-Beilage: frischer DB-Abzug
  ```

  Erzeugt der Befehl den neuen Schlüssel selbst, zeigt er ihn **genau einmal** —
  dieselbe Zeremonie wie beim Erststart, dieselbe Sofort-Pflicht: verwahren.
  🚨 **Den ALTEN Schlüssel nicht wegwerfen:** Backups von vor der Rotation
  öffnet nur er, und die Anlage führt bewusst keine Schlüssel-Historie
  (`docs/disaster-recovery.md` Abschnitt 5). Auf Hosts mit Beilage stattdessen
  sofort den täglichen Sicherungslauf für ein **neues Paar samt Probe** starten;
  den alten Key für die volle Aufbewahrungsfrist der alten Paare versiegelt behalten.
- **Updates:** reiner Abbild-Tausch nach [`docs/update-runbook.md`](update-runbook.md);
  Client-Verbindungen überleben den Neustart.
- **Mitgelieferte Kartei-Vorlagen einspielen (einmalig, optional):** Im
  Wissens-Ordner des Images liegen drei fertige Satzarten —
  `ansprechpartner` („wer hilft bei welchem IT-Produkt?"), `best_practice`
  („was hat bei uns funktioniert?") und `fachwissen` (Fachaussagen für den
  [Wissensgraphen](wissensgraph.md), gebaut, unveröffentlicht). Eine KI zeigt sie Ihnen mit
  `wissen_get vorlagen/ansprechpartner`; im Repo stehen sie unter
  `docs/wissen/vorlagen/`. So gehen sie in Betrieb:

  1. Datei nach `JNPT_KARTEIEN_DIR` kopieren (Default `/data/karteien`).
  2. Die zwei auskommentierten Zeilen setzen — **oder beide weglassen** und den
     Zugriff wie gewohnt über Scopes vergeben:

     ```yaml
     freigabe: team
     owner_team: Buchhaltung        # Name oder Team-ID
     ```

  3. `jnpt kartei check` (prüft die Datei OHNE Datenbank), dann neu starten bzw.
     SIGHUP schicken (`docker compose kill -s HUP jnpt`).

  ⚠️ Ein `owner_team` kann die Auslieferung nicht kennen — es gibt Ihre Teams
  beim Ausliefern noch gar nicht; deshalb stehen die Zeilen auskommentiert drin.
  Danach gehört die Datei **Ihnen**: Felder ergänzen, `search`/`filter` anders
  setzen — ein Update überschreibt sie nicht. Und: `ansprechpartner` trägt
  **Kontaktdaten Dritter**, die im **Klartext** an die KI gehen (die Kartei
  detokenisiert nie) — tragen Sie dort nur ein, was die KI sehen darf.

## 7. Was der Admin-MCP heute NICHT kann (ehrliche Liste)

| Lücke | Ausweg heute | Stand |
|---|---|---|
| Connector-Beschreibung einspielen | Datei + Neustart | mitgelieferte Vorlagen: über den Katalog, auch per Admin-MCP |
| Upstream-MCP-Instanzen anlegen | Datei, nur beim Start gelesen | geplant |
| Gruppen-Freigabe lesen/setzen | GUI | geplant |
| Lizenz-Token-Upload | GUI/REST/CLI oder Admin-MCP (signierter Token, kein Tresor-Credential) | `admin_install_license` — Rückfrage, Absicht vorab, Audit ohne Token |
| Credential-**Werte** | GUI/CLI (bewusste Mensch-Ausnahme) | — |

## Browser-Apps vorbereiten (Stufe 2, gebaut)

Browser-Fenster sind ab 0.91.0 gebaut und ausgeliefert. Der Kern stellt Paketabruf
und Netzvorlagen bereit; der App-Host wird separat mit dem Plugin `script-runner`
geliefert. Ein vollständiger Live-Beleg an einer echten App steht aus.
PC-Fenster und Windows-Anbindung bleiben geplant ohne Datum (PO 03.11.).
Der persönliche PC-Anmeldekern K6c-P2 ist gebaut, unveröffentlicht.
Die Admin-Seite Apps (K12) ist gebaut, unveröffentlicht bis zu einem tragenden
Release. Der Bauablauf steht im [Wissen-Muster App bauen](wissen/muster/app-bauen.md).
Apps enthalten in v1 Textdateien und SVG; PNG/ICO und andere Binärdateien
lässt die Schreibroute des Speichers nicht zu.

1. Ein überschneidungsfreies internes IPv4-Netz wählen:
   `JNPT_APPS_SUBNET=<IPv4-Netz>/<Präfix>`, `JNPT_APPS_IP=<Apps-IP>`,
   `JNPT_APPS_LISTEN=<Apps-IP>:8485`, `JNPT_APPS_DOMAIN=example.test`.
   Die Standardwerte stehen in der Compose-Vorlage.
   Bei anderem Subnetz IP und Listen-Adresse gemeinsam ändern. Ohne Apps bleiben
   LISTEN und DOMAIN leer; `JNPT_APPS_IP` bleibt gesetzt und wird an den Kern
   durchgereicht. Der Haupt-Port sperrt diese IP auch bei ausgeschalteten Apps.
   Weicht die IP in LISTEN davon ab, bricht der Start ab: beide Werte auf die
   Kern-IP im Apps-Netz setzen. Kein Host-Netz, kein veröffentlichter App-Port.
2. Auf der Box vor der Installation `python3 deploy/box/scripts/apps-netz-pruefen.py`
   aufrufen; die Prüfung weist Überschneidungen mit Host-/LAN-Routen und anderen
   Compose-Netzen ab. Die Box nutzt `tls internal` und den LAN-DNS.
3. Der Host beansprucht `/run/jnpt/plugins/apphost` nach dem Plugin-Schlüsselmuster:
   Elternordner root/0755, Kind UID 65532/0750 auf `/run` (tmpfs, nach Boot neu).
   In der menschlichen Vault-Oberfläche `plugin-apphost` mit einem zufälligen
   `jnptapphost_`-Wert mit mindestens 128 Bit Entropie belegen. Der bestehende
   Materialisierer schreibt `runtime-key`; weder in Compose noch in Logs kopieren.
4. Im DNS standardmäßig `*.apps.example.test` auf Caddy zeigen lassen.
   Alternativ für jede App einen A-Record `<name>.apps.example.test` anlegen.
   Öffentliche Zertifikate veröffentlichen diese Namen in CT-Logs: keine Kunden-,
   Personen- oder Projektnamen verwenden. Die interne Box-CA ist ausgenommen.
5. In Entra `/app-login/callback` auf dem öffentlichen Gateway ergänzen; der
   Generator berücksichtigt konfigurierte Apps automatisch. `/me/callback` bleibt.
   `offline_access` in `JNPT_SSO_AUTH_SCOPE` bleibt stehen: Der App-Fluss filtert es heraus.
6. Das Plugins-Paket liefert `apps.caddy` nach `apps.d/` und `apps-global.caddy`
   nach `apps-global.d/` neben der Compose sowie `script-runner-apphost` im Profil
   `apps`. Ohne Apps bleiben beide Verzeichnisse leer. Caddy importiert die
   globale TLS-Abfrage innerhalb seines bestehenden Optionsblocks und die
   App-Sites außerhalb. Der Logfilter entfernt `code` auch an `/_jnpt/callback`.

Der Haupt-Upstream von Caddy heißt `jnpt-main:8484` und löst ausschließlich im
Standardnetz auf. `jnpt:8484` ist bei zwei gemeinsamen Netzen nicht eindeutig.
Die Apps-IP am Haupt-Port wird unabhängig von LISTEN schon beim Accept geschlossen,
ebenso Link-Local-Quellen und -Ziele (IPv4 und IPv6, auch gemappte Adressen).
Es entstehen keine HTTP-Antwort, kein Audit und kein Anfrage-Log. Aus dem Apps-Netz
führt der Kernzugang über den privaten Listener.
