diff --git a/README.md b/README.md
index 6d8e79b84..712b3c162 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,16 @@
 A web-based Arduino simulator with a browser UI, server-side Arduino compilation
 and an interactive Arduino Preview for sketches.
 
-> **Administration:** For local development and Docker installation, see [`docs/INSTALL_LOCAL.md`](docs/INSTALL_LOCAL.md) and [`docs/INSTALL_SERVER.md`](docs/INSTALL_SERVER.md). Security requirements are in [`docs/SECURITY.md`](docs/SECURITY.md).
+## Start here
+
+| You want to … | Read |
+|---|---|
+| use UnoSim in the browser (learners, teachers) | [docs/USER_GUIDE.md](docs/USER_GUIDE.md) (German) |
+| try UnoSim in a classroom on one Ubuntu VM | [docs/INSTALL_UBUNTU_VBOX.md](docs/INSTALL_UBUNTU_VBOX.md) (German, tested end to end) |
+| run UnoSim on a server behind your own reverse proxy | [docs/INSTALL_SERVER.md](docs/INSTALL_SERVER.md) (German) and [docs/SECURITY.md](docs/SECURITY.md) |
+| develop UnoSim on your machine | [Development setup](#development-setup) below and [docs/INSTALL_LOCAL.md](docs/INSTALL_LOCAL.md) |
+| write your own examples and Tutor content | [UnoSim-Examples README](https://github.com/ttbombadil/UnoSim-Examples#course-content-and-tutor-authoring) |
+| find any other document | [docs/README.md](docs/README.md) |
 
 ## Preview
 
@@ -33,7 +42,9 @@ and an interactive Arduino Preview for sketches.
 - **Arduino Preview**: A preview of analog/digital inputs and outputs directly in the Arduino SVG
 - **Web-based UI**: Use the simulator in a browser; local/server installation runs the backend
 - **Modern UI**: Built with React and TailwindCSS for a responsive, professional interface
-- **I/O Registry**: You can see what Pins are used in your Program!
+- **I/O Registry**: See which pins your program uses
+- **Examples**: Load examples from a public GitHub repository; each browser can pick its own collection
+- **Tutor**: Learning questions about the current sketch (experimental workspace). The Tutor currently works only with KI:connect.nrw and a personal KI:connect key; other providers are tracked in [#243](https://github.com/MoDevIO/UnoSim/issues/243)
 
 ## Tech Stack
 
@@ -43,154 +54,40 @@ and an interactive Arduino Preview for sketches.
 - **Testing**: Vitest with React Testing Library
 - **Build Tools**: Vite, esbuild
 
-## Installation (only for Linux/MacOS)
+## Development setup
+
+UnoSim runs on Linux and macOS. Production always runs in Docker; see
+[docs/INSTALL_SERVER.md](docs/INSTALL_SERVER.md).
 
 ### Prerequisites
 
-- Node.js 24.20.0 LTS (see `.nvmrc`)
-- npm or yarn
+- Node.js 24.20.0 LTS (see `.nvmrc`) and npm
+- [Arduino CLI](https://arduino.github.io/arduino-cli/) with the `arduino:avr` core
 
-### Setup
+Docker is not needed for development.
 
-1. Clone the repository:
+### Setup
 
 ```bash
 git clone https://github.com/MoDevIO/UnoSim.git
 cd UnoSim
-```
-
-2. Install dependencies:
-
-```bash
-    npm ci
-```
-
-3. Start the dev-server:
-
-```bash
+npm ci
+arduino-cli core update-index
+arduino-cli core install arduino:avr
 npm run dev:full
 ```
 
-This will start both the backend server and the frontend development server.
-
-## Usage
-
-UnoSim supports two runtime profiles: local development and Docker deployment.
+Open `http://localhost:3001`. `npm run dev:full` starts the backend
+(`127.0.0.1:3000`) and the Vite dev server with hot reload; `npm run dev`
+starts only the backend. The development profile is single-user, compiles and
+runs sketches directly on your machine and accepts only loopback requests.
 
-### Development Mode
-
-```bash
-npm run dev:full
-```
-
-Starts the backend (Express + WebSocket) and the Vite dev server with hot-reload.
-The backend runs via `tsx` (TypeScript execution) and the client is served by Vite on a separate port with HMR.
-Compilation uses `arduino-cli` directly on the host — Docker is **not** required.
-
-`npm run dev` starts only the backend on the local listener (`127.0.0.1`). The
-development profile is single-user and is not a deployment mode. Both commands
-use the configured external-example source, ref, and host allowlist from the
-development script.
-
-The accepted target architecture keeps that server configuration as the
-default, while allowing each browser to select a validated public GitHub
-Examples repository and ref in Settings. The browser preference is
-request-scoped, never changes the server default, and never fetches GitHub
-directly. The default is `ttbombadil/unosim-examples` at `main`; the server
-resolves the ref to a full commit SHA before loading a complete snapshot. See
+Examples load from the public GitHub repository
+`ttbombadil/unosim-examples` at `main` by default. Each browser can choose a
+different repository under **File → Settings → External Examples** without
+changing the server default; see
 [`ssot_function_definition_ExternalExamples.md`](ssot/ssot_function_definition_ExternalExamples.md).
 
-| Component | Details |
-|-----------|---------|
-| Backend | `tsx server/index.ts` on configured `PORT` (default 3000) |
-| Client | Vite HMR dev server (proxied) |
-| Compiler | Direct `arduino-cli` calls on host |
-| Worker Pool | Disabled (`CompilerWithFallback.usePool = false` outside production) |
-
-### Docker Mode
-
-```bash
-npm run build
-npm run start
-```
-
-Builds the full stack (client + server + worker) into `dist/`. The supported
-production profile runs this server in Docker and executes every simulation in
-a Docker sandbox. The Vite-built client is served as static files from
-`dist/public/`.
-
-| Component | Details |
-|-----------|---------|
-| Backend | `node dist/index.js` on configured `PORT` (default 3000) |
-| Client | Static files from `dist/public/` |
-| Compiler | Configured Worker Pool (Compose reference: 8 parallel workers) |
-| Docker | Required for the server container and all simulation sandboxes |
-
-> **Note:** Local development compiles and executes directly on the host. The
-> Docker profile requires a working Docker daemon and sandbox image and never
-> falls back to host-native simulation.
-
-```bash
-docker build -t unosim-sandbox:latest -f Dockerfile.sandbox .
-docker build -t unosim-server:latest .
-```
-
-For a manual production container, use the same gateway, sandbox and mount
-requirements as Compose. At minimum, production requires Gateway mode,
-`UNOSIM_GATEWAY_SECRET` (at least 32 characters), `UNOSIM_TRUSTED_PROXY`, and
-`UNOSIM_ALLOWED_WS_ORIGINS`; the backend also needs the Docker socket and the
-`unosim-sandbox:latest` image available to the configured Docker daemon:
-
-```bash
-docker run --rm -p 127.0.0.1:3000:3000 \
-   -e NODE_ENV=production \
-   -e UNOSIM_SERVER_MODE=docker \
-   -e UNOSIM_GATEWAY_SECRET='<secret-from-secret-store>' \
-   -e UNOSIM_TRUSTED_PROXY='<express-trusted-proxy-ip-or-cidr>' \
-   -e UNOSIM_ALLOWED_WS_ORIGINS='https://classroom.example.edu' \
-   -e DOCKER_HOST=unix:///var/run/docker.sock \
-   -e DOCKER_SANDBOX_IMAGE=unosim-sandbox:latest \
-   -e ARDUINO_CACHE_DIR=${PWD}/server/arduino-cache \
-   -e UNOSIM_SHARED_TEMP_DIR=${PWD}/temp \
-   -v /var/run/docker.sock:/var/run/docker.sock \
-   -v ${PWD}/server/arduino-cache:${PWD}/server/arduino-cache \
-   -v ${PWD}/temp:${PWD}/temp \
-   -v ${PWD}/storage:/app/storage \
-   unosim-server:latest
-```
-
-Or with Docker Compose (backend only):
-
-```bash
-export DOCKER_GID="$(stat -c '%g' /var/run/docker.sock)"
-export UNOSIM_GATEWAY_SECRET="<at-least-32-random-characters>"
-export UNOSIM_TRUSTED_PROXY="<express-trusted-proxy-ip-or-cidr>"
-export UNOSIM_ALLOWED_WS_ORIGINS="https://classroom.example.edu"
-docker compose up --build
-```
-Compose starts the UnoSim backend only. Docker mode always requires an
-trusted reverse proxy that supplies the gateway identity; authenticating a
-person is optional. The four variables above are mandatory and must be supplied
-by the deployment's secret/environment management. The proxy must replace
-client-supplied `X-UnoSim-*` headers with the gateway secret, subject and `user`
-role for both HTTP and WebSocket requests. A private deployment may derive the
-subject from the directly observed client IP, not a client-supplied
-`X-Forwarded-For` value; clients behind the same NAT, VPN or upstream proxy
-then share an UnoSim identity and its limits. This
-IP-identified mode grants access to every client that can reach the proxy and
-is not user authentication. See [the deployment security contract](docs/SECURITY.md)
-and the [Docker installation guide](docs/INSTALL_SERVER.md). For a tested
-Ubuntu Desktop setup, see [docs/INSTALL_UBUNTU_VBOX.md](docs/INSTALL_UBUNTU_VBOX.md).
-Sandbox execution remains dynamic and uses the Docker socket at runtime.
-
-If you need SonarQube, run it separately in its own stack or service; the UnoSim compose file does not include SonarQube or MCP.
-
-The application runs inside a container and is available at `http://localhost:3000`.
-
-For sandboxed sketch execution, the server container must use a temp directory that is bind-mounted from the host at the same absolute path. The provided Compose file does this via `UNOSIM_SHARED_TEMP_DIR=${PWD}/temp` and `${PWD}/temp:${PWD}/temp`.
-
-On macOS, make sure your project directory is allowed under Docker Desktop file sharing, otherwise the inner sandbox container cannot see generated files such as `sketch.cpp`.
-
 ### Available Scripts
 
 | Command | Description |
@@ -208,13 +105,15 @@ On macOS, make sure your project directory is allowed under Docker Desktop file
 | `npm run capacity:calibrate` | Measure host/Docker simulation capacity and generate review-only Capacity recommendations |
 | `npm run test:all` | Run unit, integration and Docker gates |
 | `./run-tests.sh` | Full pipeline: lint, unit tests, Docker build, integration tests, E2E |
-| `RUN_HEAVY_TESTS=1 ./run-tests.sh` | Full pipeline inklusive langsamem Parallel-Instanz-Stresstest |
+| `RUN_HEAVY_TESTS=1 ./run-tests.sh` | Full pipeline including the slow parallel-instance stress test |
 
 For host-specific Capacity sizing, use `npm run capacity:calibrate` and follow
 the review workflow in [`docs/CAPACITY_MODEL.md`](docs/CAPACITY_MODEL.md).
 
 ### Architecture Overview
 
+The full picture is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
 - **Sandbox Runner Pool** — Manages runner leases for sketch execution. In the documented production path, each simulation runs in a short-lived isolated Docker sandbox with stdout/stderr capture for serial output and pin state reporting.
 - **Compilation Worker Pool** — In production mode, the configured Node.js Worker Thread pool handles compilations in parallel via `CompilerWithFallback`. The Compose reference uses 8 workers (the pool runs at most 8); a full pool answers `503 SYSTEM_BUSY`. Current capacity guidance is in [`docs/CAPACITY_MODEL.md`](docs/CAPACITY_MODEL.md); [`docs/CAPACITY_HISTORICAL_PHASE_3_4.md`](docs/CAPACITY_HISTORICAL_PHASE_3_4.md) keeps the historical measurement.
 - **WebSocket Layer** — Real-time communication between client and server for serial output, pin state batches, and simulation control (start/stop/pause/resume).
@@ -258,7 +157,7 @@ licenses.
 ### Getting Help
 
 - **Issues & Bugs**: Use the [GitHub Issues](https://github.com/modevio/UnoSim/issues) tracker
-- **Feature Requests**: Create an [Pull Request](https://github.com/modevio/UnoSim/pulls)
+- **Feature Requests**: Open an [issue](https://github.com/modevio/UnoSim/issues) or a [pull request](https://github.com/modevio/UnoSim/pulls)
 - **Questions**: Open a discussion or check existing issues
 
 ### Project Maintainers
diff --git a/docs/INSTALL_SERVER.md b/docs/INSTALL_SERVER.md
index 16ee6be01..561c5ac54 100644
--- a/docs/INSTALL_SERVER.md
+++ b/docs/INSTALL_SERVER.md
@@ -34,6 +34,16 @@ docker compose up --build
 Gateway-Identität und Docker-Simulation automatisch. Der Server prüft
 Docker-Daemon, Sandbox-Image und Runner-Pool vor der Readiness-Freigabe.
 
+Das Backend ist danach nur unter `127.0.0.1:3000` erreichbar und erwartet die
+Gateway-Header. Ein direkter Aufruf ohne Gateway wird mit `401` oder `403`
+abgelehnt; das ist gewollt. Zum Prüfen dienen `/api/health` und
+`/api/readiness` (siehe unten). Nutzer erreichen UnoSim ausschließlich über den
+Reverse Proxy.
+
+Für einen schnellen, durchgetesteten Aufbau auf einer einzelnen Ubuntu-VM
+installiert [INSTALL_UBUNTU_VBOX.md](INSTALL_UBUNTU_VBOX.md) Docker, Nginx und
+TLS per Skript.
+
 Die vollständige Kapazitäts- und Timeout-Semantik steht in
 [`CAPACITY_MODEL.md`](CAPACITY_MODEL.md). Die dortigen
 Validierungsprofile sind Testprofile und keine automatischen
@@ -78,6 +88,54 @@ alternative Ports müssen explizit eingetragen werden, zum Beispiel
 `https://unosim.vbox` und `https://unosim.vbox:8443`. Wildcards oder bloße
 Hostname-Suffixe sind keine Origin-Allowlist.
 
+### Beispiel: Nginx ohne Benutzeranmeldung
+
+Diese Konfiguration entspricht der des Ubuntu/VBox-Installers. Sie leitet
+HTTP und WebSocket an das Backend weiter und vergibt die Identität anhand der
+Client-IP. `unosim.example.edu` und die Zertifikatspfade sind anzupassen.
+
+```nginx
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+server {
+    listen 443 ssl;
+    server_name unosim.example.edu;
+
+    ssl_certificate     /etc/nginx/tls/unosim.crt;
+    ssl_certificate_key /etc/nginx/tls/unosim.key;
+
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header X-Real-IP $remote_addr;
+
+        # Secret in einer Datei mit Rechten 0600 halten, nicht im Site-File:
+        # proxy_set_header X-UnoSim-Gateway-Secret "<UNOSIM_GATEWAY_SECRET>";
+        include /etc/nginx/snippets/unosim-gateway-secret.conf;
+        proxy_set_header X-UnoSim-Subject "ip-$remote_addr";
+        proxy_set_header X-UnoSim-Roles "user";
+
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_read_timeout 120s;
+    }
+}
+```
+
+`proxy_set_header` überschreibt gleichnamige Header des Clients. Läuft Nginx auf
+demselben Host wie Compose, gilt `UNOSIM_TRUSTED_PROXY=172.31.253.1/32`, und
+`UNOSIM_ALLOWED_WS_ORIGINS` ist `https://unosim.example.edu`. Mit
+Benutzeranmeldung setzt das Gateway `X-UnoSim-Subject` stattdessen aus dem
+angemeldeten Konto; ein Beispiel mit HTTP Basic Auth steht in
+[INSTALL_UBUNTU_VBOX.md](INSTALL_UBUNTU_VBOX.md#optional-anmeldung-am-gateway).
+
 Der ursprüngliche Vertrag steht in
 [`adr/0001-authentication-and-gateway-contract.md`](adr/0001-authentication-and-gateway-contract.md);
 die aktuelle Entscheidung zur optionalen Benutzeranmeldung steht in
@@ -154,20 +212,20 @@ muss diese Werte nicht ändern. Für größere Installationen können sie über
 | `SIMULATION_MAX_PAUSED_SECONDS` | maximale Gesamtpausenzeit eines Simulationslaufs; danach wird er beendet und gibt seine Kapazität frei; Standard `600`, muss kleiner als `SANDBOX_MAX_LIFETIME_SECONDS` sein |
 | `WS_HEARTBEAT_INTERVAL_MS` | Ping-Intervall der WebSocket-Verbindungen; eine Verbindung ohne Antwort auf den vorherigen Ping wird getrennt und gibt ihre Simulation frei; Standard `30000` ms |
 
-Die Defaults der Anwendung stehen in `server/config.ts` (unter anderem
-`SIMULATION_MAX_CONCURRENT=5`). Die Produktions-Compose-Datei setzt aktuell
-`SIMULATION_MAX_CONCURRENT=200` ausdrücklich als Deployment-Override; das ist
-kein neuer Anwendungdefault. Dieser Wert begrenzt globale logische Runner und
-ist nicht das Limit pro Gateway-Subject. Der effektive Admission-Grenzwert pro
-Identität hängt vom verwendeten Source-Stand und dessen Konfiguration ab.
-Dieser Wert muss vor einem produktiven Einsatz
-gegen die aktuelle Zielserver-Abnahme geprüft werden. Wirksam wird er nur
-zusammen mit `SIMULATION_ADMISSION_MAX`: Ohne diesen Wert lässt die Admission
-höchstens 25 laufende und wartende Simulationen zu. Der Ubuntu/VBox-Installer
-schreibt `SIMULATION_ADMISSION_MAX=40` in die `.env`; dieser Wert ist auf der
-Referenz-VBox (8 vCPU, 11 GiB, kein Swap) für Klassen von etwa 30 Studierenden
-gemessen (siehe `CAPACITY_MODEL.md`). Auf anderer Hardware vor einer
-Übernahme erneut messen.
+Wie viele Simulationen gleichzeitig laufen, begrenzen zwei Werte gemeinsam:
+
+- `SIMULATION_MAX_CONCURRENT` begrenzt die gleichzeitig laufenden Simulationen
+  auf dem Server. Die Anwendung setzt standardmäßig `5`; `docker-compose.yml`
+  überschreibt das mit `200`.
+- `SIMULATION_ADMISSION_MAX` begrenzt laufende **und** wartende Simulationen
+  zusammen. Der Standard ist `25`.
+
+Es gilt der kleinere der beiden Werte. Mit der Compose-Datei laufen ohne
+weitere Einstellung also höchstens 25 Simulationen gleichzeitig. Der
+Ubuntu/VBox-Installer setzt `SIMULATION_ADMISSION_MAX=40`; dieser Wert ist auf
+der Referenz-VM (8 vCPU, 11 GiB RAM, kein Swap) für Klassen mit etwa 30
+Lernenden gemessen (siehe [CAPACITY_MODEL.md](CAPACITY_MODEL.md)). Auf anderer
+Hardware vor einer Übernahme neu messen.
 
 Ist der Compile-Worker-Pool ausgelastet (500 wartende Compiles oder 30 s
 Wartezeit), antwortet `/api/compile` mit `503` und `SYSTEM_BUSY`.
@@ -187,6 +245,31 @@ automatisch. Die technische Referenz mit Messphasen, Timeout-Grenzen und
 Akzeptanzkriterien steht in
 [`CAPACITY_MODEL.md`](CAPACITY_MODEL.md).
 
+### Kursinhalte und Tutor
+
+| Variable | Standard (Compose) | Zweck |
+|---|---|---|
+| `UNOSIM_EXAMPLES_SOURCE` | `ttbombadil/unosim-examples` | öffentliches GitHub-Repository mit Beispielen und Tutor-Inhalten; leer = nur eingebaute Beispiele |
+| `UNOSIM_EXAMPLES_REF` | `main` | Branch, Tag oder Commit; der Server löst ihn zu einem Commit auf |
+| `UNOSIM_EXAMPLES_ALLOWED_HOSTS` | `api.github.com,raw.githubusercontent.com` | erlaubte Ziele für ausgehende Abrufe |
+| `UNOSIM_EXAMPLES_REFRESH_MS` | `300000` | Abstand zwischen zwei Prüfungen auf einen neuen Stand |
+| `UNOSIM_GITHUB_TOKEN` | leer | siehe oben |
+| `UNOSIM_LLM_BASE_URL` | `https://chat.kiconnect.nrw/api/v1` | OpenAI-kompatibler Endpunkt für den Tutor |
+| `UNOSIM_LLM_TIMEOUT_MS` | `30000` | maximale Dauer eines Tutor-Aufrufs |
+| `TUTOR_RATE_LIMIT_MAX_REQUESTS` | `20` | Tutor-Anfragen pro Identität und Fenster |
+| `TUTOR_RATE_LIMIT_WINDOW_MS` | `60000` | Fenster für das Tutor-Limit |
+| `TUTOR_SESSION_TTL_MS` | `3600000` | absolute Lebensdauer einer Tutor-Sitzung |
+| `TUTOR_SESSION_MAX_PER_SUBJECT` | `5` | gleichzeitige Tutor-Sitzungen pro Identität |
+
+Der Tutor unterstützt derzeit nur KI:connect.nrw. Er braucht serverseitig
+keinen Schlüssel: Jede Person trägt ihren persönlichen KI:connect-Key im
+Browser ein (siehe [USER_GUIDE.md](USER_GUIDE.md#der-tutor)). Ein
+serverseitiger Schlüssel oder ein anderer Anbieter ist nicht vorgesehen;
+`UNOSIM_LLM_BASE_URL` auf einen anderen OpenAI-kompatiblen Endpunkt zu setzen
+ist weder getestet noch unterstützt. Die Verallgemeinerung ist
+[Issue #243](https://github.com/MoDevIO/UnoSim/issues/243). Ist GitHub nicht erreichbar,
+antwortet der Tutor ohne Kursinhalt als freier Tutor.
+
 Frühere Topologie- und Kompatibilitätsschalter werden beim Start abgelehnt:
 `UNOSIM_SIMULATION_MODE`, `UNOSIM_TRUST_MODE`, `FORCE_DOCKER` und
 `UNOSIM_ALLOW_INSECURE_PRODUCTION_LOCAL`.
@@ -217,6 +300,21 @@ Simulationen bleiben echte Docker-Sandboxen. Er ist kein Deploymentmodus.
 
 Eine Instanz darf erst nach erfolgreicher Readiness Traffic erhalten.
 
+## Datensicherung
+
+UnoSim speichert keine Nutzerdaten auf dem Server: Sketches existieren nur im Browser
+und werden dort über **File → Save All Files** gesichert, Tutor-Sitzungen
+liegen im Arbeitsspeicher des Backends. `storage/`, `temp/` und
+`server/arduino-cache/` enthalten nur Caches und Zwischenstände, die nach einem
+Verlust neu entstehen.
+
+Zu sichern sind:
+
+- die `.env` bzw. die Umgebungswerte, vor allem `UNOSIM_GATEWAY_SECRET`
+  (vertraulich ablegen),
+- die Gateway-Konfiguration samt TLS-Zertifikat und -Schlüssel,
+- der eingesetzte Source-Stand (Commit oder Image-Tag) für ein Rollback.
+
 ## Update und Rollback
 
 1. Images aus dem vorgesehenen Commit bauen und taggen.
diff --git a/docs/OPEN_POINTS.md b/docs/OPEN_POINTS.md
index 2d0cb4613..8c8761b79 100644
--- a/docs/OPEN_POINTS.md
+++ b/docs/OPEN_POINTS.md
@@ -28,6 +28,12 @@ Statuswerte: `BLOCKED_DECISION` (wartet auf eine Entscheidung) · `DEFERRED`
 | D4 | Tutor-Sessions laufen nach einer absoluten TTL ab (Default 1 h, per `TUTOR_SESSION_TTL_MS` einstellbar), auch bei laufender Nutzung. | gering | [config.ts:412](../server/config.ts#L412), [course-content-session.ts:107](../server/services/course-content/course-content-session.ts#L107) | BLOCKED_DECISION | Absolute oder gleitende TTL? |
 | D5 | Ein laufender Sketch hält seinen Simulationsslot bis zum Lauf-Timeout (Default 60 s, Client-Maximum 300 s). Pausierte Läufe enden nach `SIMULATION_MAX_PAUSED_SECONDS` (600 s), jeder Container nach `SANDBOX_MAX_LIFETIME_SECONDS` (2 h). Einen Inaktivitäts-Timeout für laufende Simulationen gibt es nicht. | gering | [input-limits.ts:40-42](../shared/input-limits.ts#L40-L42), [config.ts:246-247](../server/config.ts#L246-L247) | BLOCKED_DECISION | Reichen die vorhandenen Grenzen, oder soll eine Simulation ohne Nutzerinteraktion früher enden? |
 
+## Erweiterungen
+
+| ID | Befund | Risiko | Beleg | Status | Nötige Entscheidung |
+|---|---|---|---|---|---|
+| TUTOR-PROVIDER | Der Tutor funktioniert nur mit KI:connect.nrw und persönlichen Keys; das beschränkt ihn praktisch auf Schulen und Hochschulen in NRW. | gering | [config.ts:667-670](../server/config.ts#L667-L670), [tutor.routes.ts:129](../server/routes/tutor.routes.ts#L129), [Issue #243](https://github.com/MoDevIO/UnoSim/issues/243) | BLOCKED_DECISION | Credential-Modell (nur persönliche Keys oder auch Server-Key) und Provider-Abstraktion festlegen |
+
 ## Wartung
 
 | ID | Befund | Risiko | Beleg | Status | Nötige Entscheidung |
diff --git a/docs/README.md b/docs/README.md
index de395804c..857cf9c67 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -5,8 +5,20 @@ Architektur. Weitere Dateien in diesem Verzeichnis sind als historisch oder
 nicht normativ gekennzeichnet (Kopfzeile); sie dokumentieren Analysen, Pläne
 und Messläufe, keinen Vertrag.
 
+## Nutzung
+
+- [USER_GUIDE.md](USER_GUIDE.md) – UnoSim im Browser bedienen: Sketches,
+  Simulation, Beispiele und Tutor.
+- [UnoSim-Examples](https://github.com/ttbombadil/UnoSim-Examples#course-content-and-tutor-authoring)
+  – eigene Beispiele und Tutor-Inhalte erstellen.
+
 ## Installation und Betrieb
 
+Für einen ersten Klassenraum-Aufbau ist
+[INSTALL_UBUNTU_VBOX.md](INSTALL_UBUNTU_VBOX.md) der kürzeste Weg; für einen
+eigenen Reverse Proxy gilt [INSTALL_SERVER.md](INSTALL_SERVER.md).
+
+
 - [INSTALL_LOCAL.md](INSTALL_LOCAL.md) – lokale Entwicklung mit lokaler
   Kompilierung und Simulation.
 - [INSTALL_SERVER.md](INSTALL_SERVER.md) – Docker-Deployment mit erforderlichem
diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md
new file mode 100644
index 000000000..9f72fa970
--- /dev/null
+++ b/docs/USER_GUIDE.md
@@ -0,0 +1,119 @@
+# UnoSim benutzen
+
+Diese Anleitung richtet sich an Lernende und Lehrkräfte, die UnoSim im Browser
+verwenden. Installation und Betrieb beschreibt die
+[Dokumentationsübersicht](README.md). Die Oberfläche
+ist englisch; die Menünamen stehen hier deshalb in der Originalschreibweise.
+
+## Überblick
+
+UnoSim simuliert einen Arduino Uno im Browser. Du schreibst einen Sketch,
+kompilierst ihn auf dem UnoSim-Server und siehst die Ausgabe im Serial Monitor
+und am Board. Du brauchst dafür keine Hardware und keine Installation.
+
+## Einen Sketch schreiben und starten
+
+1. Den Code im Editor schreiben. Weitere Dateien legst du mit **File → New File**
+   an; jede Datei erscheint als eigener Tab.
+2. Mit **Start** in der Kopfzeile kompilieren und die Simulation starten.
+   Fehler beim Kompilieren erscheinen im Output Panel unter dem Editor.
+3. Ausgaben von `Serial.print` erscheinen im **Serial Monitor**. Eingaben an den
+   Sketch schickst du über das Feld **Send to Arduino...**.
+4. Das **Board** zeigt den Zustand der Pins. Einen als `INPUT` genutzten Pin
+   schaltest du per Klick um; analoge Eingänge stellst du mit einem
+   Schieberegler ein.
+5. Mit **Pause** hältst du die Simulation an, um Pins in Ruhe zu prüfen oder zu
+   verändern; mit **Resume** läuft sie weiter. **Stop** beendet den Lauf.
+
+Ein Lauf endet automatisch nach seiner Laufzeit, die du unter
+**Tools → Timeout** zwischen 5 Sekunden und 5 Minuten wählst. Eine pausierte
+Simulation endet spätestens nach insgesamt 10 Minuten Pause.
+
+## Arbeit sichern
+
+Der Server speichert keine Sketches. Sichere deine Dateien mit
+**File → Save All Files** und lade sie später mit **File → Load Files** wieder.
+
+## Beispiele laden
+
+**Examples** in der Kopfzeile (oder `Cmd/Ctrl+E`) öffnet die Beispielsammlung.
+Ein Beispiel ersetzt nach Rückfrage den aktuellen Sketch.
+
+Lehrkräfte können für ihren Browser eine eigene Beispielsammlung wählen:
+
+1. **File → Settings** öffnen, Abschnitt **External Examples**.
+2. Unter **Repository** ein öffentliches GitHub-Repository eintragen
+   (`owner/repository` oder die GitHub-URL), unter **Ref** einen Branch oder
+   Tag (Standard `main`).
+3. **Validate** prüft die Sammlung, **Apply** übernimmt sie.
+   **Reset to default** kehrt zur Sammlung des Servers zurück.
+
+Die Auswahl gilt nur für diesen Browser und ändert nichts an der Einstellung
+des Servers. Wie man eine eigene Sammlung samt Tutor-Inhalten aufbaut,
+beschreibt das
+[README von UnoSim-Examples](https://github.com/ttbombadil/UnoSim-Examples#course-content-and-tutor-authoring).
+
+## Der Tutor
+
+Der Tutor stellt Lernfragen zu deinem aktuellen Sketch und gibt Rückmeldung auf
+deine Antworten. Er schreibt keine fertige Lösung.
+
+### Tutor einschalten
+
+Der Tutor ist Teil des neuen Arbeitsbereichs, der noch als experimentell gilt:
+
+1. **File → Settings** öffnen.
+2. Unter **Workspace & Interaction** die Option
+   **Experimental Workspace Layout** einschalten.
+
+Code, Simulation und Tutor erscheinen dann als eigene Spalten, die du einzeln
+ein- und ausblenden kannst.
+
+### API-Key eintragen
+
+Der Tutor nutzt ein Sprachmodell über KI:connect.nrw und braucht dafür deinen
+**persönlichen KI:connect-API-Key**. Den Key bekommst du über deine Schule oder
+Hochschule. Ein anderer Anbieter oder ein anderer Zugang ist derzeit nicht
+möglich; ohne KI:connect-Key steht der Tutor nicht zur Verfügung. Die
+Unterstützung weiterer Anbieter ist in
+[Issue #243](https://github.com/MoDevIO/UnoSim/issues/243) geplant.
+
+1. In der Tutor-Spalte auf das Schlüssel-Symbol klicken
+   (**API key missing**).
+2. Den Key unter **API key** eintragen. Unter **Model** kannst du ein Modell
+   wählen; **Automatic** ist die Voreinstellung.
+3. Optional die **Start difficulty** setzen: 1 ist sehr leicht, 100 sehr schwer.
+   Der Tutor passt die Schwierigkeit danach selbst an.
+
+Der Key bleibt nur in diesem Browser-Tab im Arbeitsspeicher. Nach einem
+Neuladen der Seite musst du ihn erneut eintragen. UnoSim speichert ihn nicht.
+
+### Mit dem Tutor arbeiten
+
+1. Mit dem Fragezeichen-Symbol in der Tutor-Spalte eine neue Lernfrage anfordern.
+2. Die Antwort in das Feld **Your answer …** schreiben und mit
+   **Send answer** abschicken.
+3. Der Tutor bewertet dein Verständnis und stellt genau eine Folgefrage.
+
+Stammt dein Sketch aus einer Beispielsammlung mit Tutor-Inhalten, folgt der
+Tutor dem dort hinterlegten Lernpfad. Sonst – und auch, wenn GitHub gerade
+nicht erreichbar ist – arbeitet er als freier Tutor direkt mit deinem Sketch.
+
+## Einstellungen
+
+Unter **File → Settings** findest du außerdem:
+
+- **UI Font Size**: Schriftgröße von Oberfläche und Editor (S bis XXL),
+- **Arduino Color**: Farbe des Boards,
+- **Pin Monitor**: Pin-Übersicht über dem Board,
+- **Toast Duration**: Anzeigedauer von Hinweisen.
+
+## Wenn etwas nicht klappt
+
+| Meldung oder Verhalten | Ursache und Lösung |
+|---|---|
+| **Server connection required** | Der Browser erreicht den UnoSim-Server nicht. Verbindung prüfen und die Seite neu laden. |
+| **Waiting for compile slot** oder **Waiting for simulation slot** | Viele Nutzer kompilieren oder simulieren gleichzeitig; UnoSim startet deinen Lauf, sobald ein Platz frei ist. |
+| **Enter your personal Tutor API key first.** | Es ist noch kein Key eingetragen, oder die Seite wurde neu geladen. |
+| **The Tutor access was rejected.** | Der Key ist ungültig oder abgelaufen. |
+| Fehler im Output Panel nach **Start** | Der Sketch kompiliert nicht. Die Zeilenangabe in der Meldung zeigt auf die Fehlerstelle. |