# Werkzeug-API – ein Lernwerkzeug andocken

Ein **Lernwerkzeug** ist eine fremde Webseite (Übungen, Simulationen, Aufgabenformate), die Stundentakt als
Baustein in ein Medium einbindet. Stundentakt startet sie; sie meldet die Person per OAuth an (Code mit PKCE),
holt mit dem Zugriffstoken ihre Aufgabe, speichert Zwischenstände, meldet Ergebnis und Ereignisse zurück. Die Seite des Werkzeugs wird
von Stundentakt nie ausgeführt, nur eingerahmt. Die Gegenstelle im Werkzeug ist `tool-link.js`
(`stundentakt-subjects/packages/kit`); dieses Dokument ist der Vertrag dazu.

Dieses Dokument ist die Referenz. Einstieg: `/developers` (Seite für Menschen), `/docs/developers/overview.md`,
`/docs/developers/quickstart.md`, `/docs/developers/recipes.md`. Maschinenlesbar: `/llms.txt` (nach llmstxt.org),
`/llms-full.txt` und `/api/v1/tools/openapi.json` (OpenAPI 3.1, ohne Token, darf 5 Minuten zwischengespeichert werden).

## 1 Überblick

- Ein Eintrag unter **Werkzeuge** (`/tools`) beschreibt ein Werkzeug: Name, Start-Adresse, Rücksprungadressen,
  Anzeige. Jeder Eintrag ist ein öffentlicher OAuth-Client (ohne Secret); seine `client_id` (eine UUID) steht
  am Eintrag.
- Ein Baustein `tool` im Medium verweist auf einen Eintrag und trägt Titel, Aufgabe (`task`) und einen
  versteckten Teil (`hidden`, nur für die Autor:in und das Werkzeug in ihrer Hand).
- **Modi** (`mode` in der Start-Adresse):
  - `learn`: eine Schüler:in oder eine mitmachende Lehrer:in bearbeitet die Aufgabe.
  - `review`: eine Lehrer:in liest die abgegebene Antwort einer Schüler:in ihrer Klasse (nur lesen).
  - `author`: die Lehrer:in schreibt die Aufgabe selbst (Titel, Aufgabe, versteckter Teil).
- **Anzeige:** `inline` (Rahmen in der Seite) oder `full` (Karte, die ein eigenes Fenster öffnet). Der Eintrag gibt
  sie vor; ein Baustein kann sie für sich überschreiben (`payload.display`, Abschnitt 5).
- **Rollen:** Lehrer:in (`User`) und Schüler:in (`Member`). Das Werkzeug sieht von einer Schüler:in nur das Pseudonym,
  von einer Lehrer:in ihren Anzeigenamen („J. Muster“; beides `alias`, Abschnitt 5b), nie eine E-Mail. Ein **Gast** (`Member` ohne Klasse) ist für ein Werkzeug nicht angemeldet: Er
  bekommt kein Token, das Werkzeug speichert für ihn höchstens lokal.

## 2 Eintragen

| Feld | Regel |
|---|---|
| `name` | Pflicht, kurz |
| `launch_url` | Pflicht: `https://` (`http://` nur für `localhost`, `127.0.0.1`, `[::1]`), ohne Benutzer:in/Passwort, ohne `#`, nicht auf Stundentakt selbst |
| `redirect_uris` | Rücksprungadressen für OAuth, bis zu 10: `https://` (`http://` nur für `localhost`, `127.0.0.1`, `[::1]` in Entwicklung und Test), ohne Benutzer:in/Passwort, ohne `#`, nicht auf Stundentakt selbst |
| `display` | `inline` oder `full` |

**Im Werkzeug einstellen:** die `client_id` des Eintrags und als `redirect_uri` genau eine der eingetragenen
Rücksprungadressen, Zeichen für Zeichen (Schema, Host, Port, Pfad; die Query zählt beim Vergleich von `next` nicht,
bei `redirect_uri` schon). Nutzt ein Werkzeug die Seite selbst als Rücksprung (wie `tool-link.js`: Origin und Pfad
der Seite), trägt der Eintrag jede solche Seite ein, z. B. `https://werkzeug.example/embed/`. Dieselben Adressen
erlaubt Stundentakt als `next` beim An- und Abmelden (Abschnitt 8); eine andere Seite fürs Abmelden kommt ebenso
dazu.

Die **Origin** der Adresse (Schema, Host, Port) ist die einzige Origin, von der aus die API antwortet. Ein
Eintrag gehört einer Schule oder allen (globale Einträge legt der Betreiber an). Ein **gesperrter** Eintrag
(Betreiber) startet nicht mehr, `/oauth/authorize` weist ihn ab (`error=access_denied&reason=tool_unavailable`
an die Rücksprungadresse), seine Tokens antworten sofort mit `tool_unavailable`, Erneuern scheitert. Ein
gelöschter Eintrag nimmt Client und Tokens mit (danach `token_invalid`).

## 3 Start

Stundentakt öffnet die Adresse so (Reihenfolge der Parameter nicht verbindlich):

```
https://werkzeug.example/start?mode=learn&assignment=<ULID>&block=<ULID>&lang=de
```

| Modus | Parameter |
|---|---|
| `learn` | `assignment`, `block` |
| `review` | `assignment`, `block`, `response` |
| `author` | `document`, `block` |

Dazu immer `lang` (`de` oder `en`, die Sprache der Seite, die das Werkzeug öffnet). Das Werkzeug zeigt sich in
dieser Sprache und schickt sie als `Accept-Language` mit; danach richten sich `message` eines Fehlers und
`entitlements.plan_name` (ohne die Kopfzeile: Englisch). Eigene Parameter in
`launch_url` bleiben erhalten, gleichnamige überschreibt Stundentakt. Alle Werte außer `mode` und `lang` sind
ULIDs. Die Adresse trägt **kein Token**; das Werkzeug meldet die Person selbst an (Abschnitt 4).

Im Modus `inline` steht das Werkzeug in einem Rahmen (`iframe`) einer Stundentakt-Seite
(`/tools/launch/{block}?frame=1`), sonst öffnet `/tools/launch/{block}` ein eigenes Fenster. Maßgeblich ist die
Anzeige des Bausteins (`payload.display`), ohne eigene die des Eintrags; einen Baustein mit `full` rahmt der Start im
Modus `learn` nie ein, auch nicht mit `frame=1`. Der Anbieter muss
das Einrahmen durch `https://stundentakt.eu` zulassen (kein `X-Frame-Options: DENY`; `frame-ancestors`
nennt Stundentakt).

## 4 Anmelden mit OAuth

Code-Ablauf nach RFC 6749 mit PKCE (RFC 7636, nur `S256`), öffentlicher Client ohne Secret. Eine Zustimmung
fragt Stundentakt bei eingetragenen, nicht gesperrten Werkzeugen nicht ab.

**1. Code holen.** Das Werkzeug erzeugt einen `code_verifier` (43–128 Zeichen aus `A-Z a-z 0-9 - . _ ~`) und
daraus die `code_challenge`, und navigiert (im Rahmen oder im eigenen Fenster) zu:

```js
const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
const challenge = base64url(new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))));
sessionStorage.setItem('pkce', verifier);
location.href = 'https://stundentakt.eu/oauth/authorize?' + new URLSearchParams({
  client_id: '<client_id des Eintrags>', redirect_uri: 'https://werkzeug.example/callback',
  response_type: 'code', scope: 'tools:write', state: '<Zufall>', prompt: 'none',
  code_challenge: challenge, code_challenge_method: 'S256',
});
```

Zurück kommt `https://werkzeug.example/callback?code=…&state=…`. `redirect_uri` muss genau eine eingetragene
Rücksprungadresse sein, sonst geht nichts zurück (`401 invalid_client`, kein Rücksprung).

**`prompt=none`** (still, nach OpenID Connect): Ist die Person in Stundentakt angemeldet, kommt sofort ein Code;
sonst `error=login_required` statt der Anmeldeseite. Beim Start aus Stundentakt besteht die Sitzung, also holt
das Werkzeug den Code still. Ohne `prompt` zeigt Stundentakt die Anmeldeseite (`/login?next=…`, alle Wege) und
kehrt danach zum Authorize-Schritt zurück; ein unvollständiges Lehrer:innen-Konto bestätigt erst die E-Mail
bzw. die Einwilligung.

Im Rahmen navigiert das Werkzeug seinen eigenen Rahmen zu `/oauth/authorize`. Ein Browser schickt bei einer
Navigation, die eine fremde Seite in einem Rahmen auslöst, kein `SameSite=Lax`-Cookie mit, obwohl die Seite darum
stundentakt.eu ist. Stundentakt antwortet darauf einmal mit einer kleinen eigenen Seite, die dieselbe Adresse
erneut aufruft (`meta refresh`); diese Navigation startet stundentakt.eu selbst, das Sitzungs-Cookie kommt mit,
und der Rücksprung folgt wie sonst. Für das Werkzeug ändert sich nichts.

**Rahmen auf einer fremden Seite** (nicht Stundentakt): Auch dort antwortet Stundentakt einmal mit dieser Seite.
Sie darf in jedem Rahmen stehen (`frame-ancestors *`, ohne `X-Frame-Options`), denn sie zeigt nichts zum Anklicken,
nur die Weiterleitung. Ihr zweiter Aufruf kommt von stundentakt.eu selbst und zeigt die Seite nie wieder; weil die
äußere Seite fremd ist, schickt der Browser trotzdem kein Cookie, und mit `prompt=none` kommt `login_required` an
der Rücksprungadresse an, ohne Schleife. Das Werkzeug bietet dann ein eigenes Fenster zum Anmelden an (Abschnitt 8)
und fragt danach still erneut. Ohne `prompt=none` führte der zweite Aufruf zur Anmeldeseite, die in keinem fremden
Rahmen steht; im Rahmen also immer `prompt=none`. Jede andere Seite unter `/oauth/authorize` bleibt nicht einbettbar.

Rücksprünge ohne Code:

| `error` | `reason` | Bedeutung |
|---|---|---|
| `login_required` | – | `prompt=none`, niemand angemeldet |
| `interaction_required` | – | `prompt=none`, Lehrer:innen-Konto unvollständig (E-Mail unbestätigt oder Einwilligung fehlt); ohne `prompt` führt Stundentakt erst dorthin |
| `access_denied` | `guest_not_supported` | ein Gast ist für Werkzeuge nicht angemeldet |
| `access_denied` | `tool_unavailable` | Eintrag gesperrt |
| `invalid_request` | – | `code_challenge_method` ist nicht `S256` |

**2. Code tauschen** (`POST /oauth/token`, Formular oder JSON, ohne Cookies):

```
grant_type=authorization_code&client_id=<client_id>&redirect_uri=https://werkzeug.example/callback
&code=<code>&code_verifier=<verifier>
```

```json
{"token_type": "Bearer", "expires_in": 900, "access_token": "eyJ…", "refresh_token": "def5…"}
```

**3. Erneuern** vor Ablauf oder nach `token_expired`:

```
grant_type=refresh_token&client_id=<client_id>&refresh_token=<refresh_token>
```

Die Antwort hat dieselbe Form; das alte Erneuerungstoken und das alte Zugriffstoken sind danach verbraucht
(Rotation). Scheitert das Erneuern (`400 invalid_grant`), holt das Werkzeug still einen neuen Code
(`prompt=none`); kommt `login_required`, ist die Person abgemeldet.

- **Zugriffstoken:** Träger-Token (`Authorization: Bearer …`), **15 Minuten**.
- **Erneuerungstoken:** rotierend, verfällt nach **30 Minuten ohne Erneuern** (so lange wie eine Sitzung in
  Stundentakt ohne Aktivität). Bleibt die Person dort angemeldet („Angemeldet bleiben“), holt das Werkzeug
  danach still einen neuen Code.
- **Subjekt** (`sub`): `user:<ULID>` oder `member:<ULID>`, nie eine interne Nummer.
- **Scopes:** siehe Tabelle; ohne Scope gilt keiner (`wrong_scope`), andere Scopes erhält ein Werkzeug nie.
- Ein Token gilt für **ein** Werkzeug und **eine** Person; es ist nie mehr als die Person selbst und erreicht
  weder die KI-/MCP-Schnittstelle noch eine andere Stelle von Stundentakt.
- Widerrufen werden Zugriffs- **und** Erneuerungstoken: beim Abmelden in Stundentakt (auch wenn sich im selben
  Browser eine andere Person anmeldet), beim `POST logout` (Abschnitt 8), beim Sperren oder Löschen des Eintrags
  und beim Löschen der Person.

### Scopes

| Scope | wofür | erlaubt |
|---|---|---|
| `tools:read` | Modus `review` | alle Routen mit Scope `read` in Abschnitt 5 |
| `tools:write` | Modi `learn` und `author` | alle Routen (`read` und `write`) |

### Ablauf im Rahmen und im eigenen Fenster

Beide Wege sind derselbe OAuth-Ablauf; sie unterscheiden sich nur darin, wo das Werkzeug navigiert.

| Schritt | im Rahmen (`inline`) | im eigenen Fenster (`full`, direkter Aufruf, F5) |
|---|---|---|
| Start | Stundentakt rahmt `launch_url?mode=…&lang=…` ein, die Person ist angemeldet | `/tools/launch/{block}` öffnet dieselbe Adresse; ein Lesezeichen oder F5 öffnet sie direkt |
| Code | der Rahmen navigiert zu `/oauth/authorize?…&prompt=none` | das Fenster navigiert zu `/oauth/authorize?…&prompt=none` |
| ohne Cookie | Stundentakt antwortet einmal mit der Nachfrage-Seite, die dieselbe Adresse selbst erneut aufruft; danach kommt der Code | – |
| niemand angemeldet | `error=login_required`: das Werkzeug bietet „In Stundentakt anmelden“ an, öffnet den Authorize-Schritt **ohne** `prompt` in einem neuen Fenster und fragt danach im Rahmen erneut still | `error=login_required`: dieselbe Adresse ohne `prompt` führt über `/login?next=…` und zurück |
| Konto unvollständig | `error=interaction_required`: wie oben ohne `prompt` | ohne `prompt` erst E-Mail-Bestätigung bzw. Einwilligung, dann zurück |
| Token | `POST /oauth/token` mit `code_verifier` | ebenso |
| F5 / neuer Tab | Tokens am besten im `sessionStorage` des Werkzeugs; fehlen sie, still neu mit `prompt=none` | ebenso |
| Abmelden | `POST logout` (Abschnitt 8) | `POST logout`, dann auf Wunsch `/logout?next=<Rücksprungadresse>` |

Tokens reisen nie über `postMessage`, nie in einer Adresse und nie zwischen Rahmen und Seite: jede Seite des
Werkzeugs holt sich ihre eigenen.

## 5 Routen

Basis: `https://stundentakt.eu/api/v1/tools`. Alle Antworten sind JSON. Fehler siehe Abschnitt 6.

| Methode | Pfad | Scope | Zweck |
|---|---|---|---|
| GET | `documents/{document}` | read | Modus `author`: Name des Mediums, Bausteine dieses Werkzeugs samt `hidden`, soweit die Person sie ändern darf, und das ganze Medium (`content`) |
| GET | `assignments/{assignment}` | read | Modi `learn`, `review`: Zuweisung, Fenster, `me`, Bausteine dieses Werkzeugs, das ganze Medium (`content`), eigener Fortschritt (`progress`) |
| PUT | `blocks/{block}` | write | `author`: `title`, `task`, `hidden`, `display`, `complete` (`false` speichert einen Entwurf, den keine Klasse sieht), `updated_at` als Vorbedingung; alles optional |
| GET | `assignments/{assignment}/blocks/{block}/draft` | read | eigener Zwischenstand (`draft.state`) und eigene Abgabe (`response`) |
| PUT | `assignments/{assignment}/blocks/{block}/draft` | write | `{state}` speichern |
| POST | `assignments/{assignment}/blocks/{block}/response` | write | Ergebnis abgeben: `done`, `score`, `max_score`, `state`, `attachments` |
| GET | `assignments/{assignment}/blocks/{block}/response/{response}` | read | `review`: eine Antwort der Klasse lesen |
| POST | `assignments/{assignment}/blocks/{block}/attachments` | write | Datei hochladen (`multipart`, Felder `type`=`file` und `attachment`; dieselbe Route-Logik wie das Antwortformular der App); die ULID kommt in `attachments` des Ergebnisses |
| POST | `assignments/{assignment}/events` | write | Lernereignisse im Unterricht melden |
| POST | `events` | write | Lernereignisse ohne Unterricht melden (Person + Werkzeug) |
| GET | `blocks/{block}/note` | read | eigene Notiz zum Baustein |
| PUT | `blocks/{block}/note` | write | `{note}` speichern (leer löscht) |
| GET | `me` | read | wer angemeldet ist und was ihr Abo freischaltet (Abschnitt 5b) |
| GET | `me/assignments` | read | „Meine Kurse“: Zuweisungen der Person mit Bausteinen dieses Werkzeugs (Abschnitt 5c) |
| GET | `links/resolve` | read | eine Stundentakt-Adresse oder einen Code als Zuweisung der Person öffnen (`?url=`, Abschnitt 5c) |
| POST | `logout` | read | Tokens der Person in allen Werkzeugen widerrufen |
| GET | `collections/{collection}/records` | read | eigene Records einer Datenart, mit `?scope=shared` die für die Person freigegebenen anderer (Abschnitt 5a) |
| GET | `collections/{collection}/records/{record}` | read | einen Record lesen: eigener oder freigegebener |
| POST | `collections/{collection}/records` | write | Record anlegen: `data`, `schema`, `visibility` |
| PATCH | `collections/{collection}/records/{record}` | write | eigenen Record ändern: `data`, `schema`, `visibility`, Pflicht `updated_at` |
| DELETE | `collections/{collection}/records/{record}` | write | eigenen Record löschen |
| GET | `records/{record}` | – | öffentlichen Record lesen, **ohne Token** |

Antworten im Einzelnen:

- `GET documents/{d}`: `document` (`ulid`, `name`, `type`), `blocks` (die Bausteine dieses Werkzeugs: `ulid`, `type`,
  `payload` mit `tool`, `title`, `task`, `display`, dazu `updated_at` und `hidden`, wenn die Person den Baustein ändern
  darf), `content` (siehe unten).
- `payload.display`: `inline`, `full` oder `null`. `null` heißt: wie am Eintrag eingestellt. Die Lehrer:in wählt es
  im Baustein („Anzeige“), das Werkzeug setzt es mit `PUT blocks/{b}`; jeder andere Wert ist `422 invalid`.
- `GET assignments/{a}`: `assignment` (`ulid`, `mode`, `visible_from/until`, `open_from`, `closes_at`; `open_from`
  ist der Beginn, `closes_at` die Frist), `document`, `window` (`phase`, `takes_answers`), `me` (`role`:
  `teacher|student|guest`, `alias`: derselbe Name wie in `GET me`, bei einer Schüler:in ihr Pseudonym, bei einer
  Lehrer:in ihr Anzeigename), `blocks` (wie oben, dazu die Bausteine dieses Werkzeugs, die die Klasse
  ergänzt hat), `content` und `progress`.
- `content`: das ganze Medium in der Reihenfolge der Seite, ein Kind direkt hinter seinem Eltern-Baustein. Jeder
  Eintrag hat `ulid`, `type`, `position`, `parent` (ULID oder `null`) und `own`:
  - `own: true`: ein Baustein dieses Werkzeugs, in derselben Form wie in `blocks`.
  - `own: false`: jeder andere Baustein (Text, Bild, Aufgabe, ein anderes Werkzeug …) mit `text`, der lesbaren
    Fassung des Bausteins (Markdown, dieselbe wie für die KI-Schnittstelle). `payload` (öffentlicher Teil) nur für
    die Person, die den Baustein ändern darf. `solution` nur, wo die App die Lösung zeigt: nach der Frist der
    Klasse, der Lehrer:in der Klasse immer, nie über `documents/{d}`.
  - Bild und Galerie tragen `images: [{url, alt}]`. `url` ist eine signierte Adresse, die 5 Minuten gilt und
    ohne Cookie von der Seite des Werkzeugs lädt (`<img src>`); danach holt das Werkzeug den Eintrag neu. Sie geht
    nur an eine Person, die den Baustein sehen darf.
  - Ein Verweis auf ein Medium (Kurs: die Stunde `lesson` mit ihren Verweisen als Kindern) trägt `medium`:
    `{ulid, name, type, assignment}` mit der Zuweisung dieses Mediums an die Klasse (oder `null`); nimmt die Person
    dort teil, dazu ihr `progress` (Form wie unten). `medium` ist `null`, solange die Klasse das Medium nicht
    öffnen kann. Eine Stunde, die noch bevorsteht, zeigt der Klasse nur sich selbst, ohne ihre Kinder.
  - Wer das Medium baut (`documents`) oder die Klasse leitet (`assignments`), sieht alle Bausteine. Alle anderen
    sehen, was die Klasse sieht: Bausteine nur für Lehrer:innen und unfertige Bausteine fehlen samt ihren Kindern.
    Beiträge einer Klasse (Karten, Feed) gehören nicht zum Medium und fehlen.
- `progress`: `{done, total, blocks: [{ulid, done}]}`, die eigenen Antworten der Person auf die Aufgaben, die die
  Klasse sieht; dieselbe Zählung wie der Fortschritt in der App, Antworten einer Live-Runde zählen nicht.
- `GET …/draft`: `{draft: {state, updated_at} | null, response: {payload: {done, score, max_score, state}, submitted_at, returned} | null}`.
  Eine Abgabe löscht den Entwurf: Steht ein Entwurf neben einer Abgabe, ist er neuer als sie.
- `GET …/response/{r}`: `{ulid, alias, payload, submitted_at, returned}`; `alias` ist der Name wie in `GET me`, bei
  einer Schüler:in ihr Pseudonym.
  Gibt es die Antwort nicht mehr (zurückgezogen oder entfernt), `404 withdrawn`.
- `PUT blocks/{b}`: Antwort `{complete, incomplete, block}`. Was der Körper weglässt, bleibt (auch `hidden` und
  `display`; `display: null` gibt die Anzeige an den Eintrag zurück).
  Mit `updated_at` (so, wie das Werkzeug es zuletzt gelesen hat) speichert die Route nur, wenn sich die Aufgabe
  seitdem nicht geändert hat, sonst `409 conflict` mit dem aktuellen Stand in `block`; ohne `updated_at` gewinnt
  der letzte Aufruf. Verglichen wird auf die Sekunde.
- `POST …/response`: `{ok: true}`. Eine neue Abgabe ersetzt die frühere. Abgabe und Datei sind dieselben Wege wie das
  Antwortformular der App (gleiche Action, gleiche Regeln), nur mit dem Token statt der Sitzung.
  `score` ist das Wort des Werkzeugs; niemand prüft es nach.
- `POST …/events` und `POST events`: Körper `{events: [{block?, verb, code?, object?, result?, timestamp?}]}`,
  Antwort `201 {recorded: n}`. Die Form folgt einer xAPI-Aussage (Person, Verb, Objekt, Ergebnis, Zeit), ohne
  Lernspeicher und ohne JSON-LD. Person und Werkzeug sind immer die des Tokens, nie aus dem Körper; ein Werkzeug
  schreibt also nie ein Ereignis für ein anderes. Ein Aufruf wird ganz oder gar nicht gespeichert.
  - **Im Unterricht** (`assignments/{a}/events`): die Person nimmt an der Zuweisung teil (wie bei der Abgabe); das
    Ereignis gehört zur Zuweisung, mit `block` auch zum Baustein. Nur Ereignisse mit `block` zählen in der
    Auswertung der Klasse.
  - **Ohne Unterricht** (`events`): z. B. eine gelernte Vokabel im freien Gebrauch. Das Ereignis gilt nur Person und
    Werkzeug: kein `block` (sonst `422 invalid`), als `object` nur ein eigener `record`.
  - `block`: ULID eines Bausteins dieses Werkzeugs in der Zuweisung; ohne `block` gilt das Ereignis der Zuweisung.
  - `verb`: freies Wort des Werkzeugs (≤ 40 Zeichen). Empfohlen, weil Stundentakt sie auswertet: `run` (ausgeführt),
    `error` (Fehler, mit `code`), `step` (Schritt geschafft), `submit` (abgegeben), `reset` (neu begonnen).
  - `code`: freier Fehlercode des Werkzeugs (≤ 80 Zeichen), z. B. `err.script.indent`.
  - `object`: `{type, id}` mit `type` = `block` (ULID eines Bausteins dieses Werkzeugs in der Zuweisung) oder
    `record` (ULID eines eigenen Records der Person in diesem Werkzeug; ein freigegebener fremder Record zählt nicht).
    Passt das Objekt nicht, `422 invalid` mit dem Feld in `errors`. Wird der Record gelöscht, bleibt das Ereignis
    ohne Objekt stehen.
  - `result`: nur `success` (`true`/`false`), `score` und `duration`, höchstens 2 KB. `score` ist eine Zahl von 0 bis 1
    oder `{raw?, min?, max?, scaled?}` (Zahlen, `min` ≤ `raw` ≤ `max`, `scaled` von 0 bis 1); eine Zahl wird als
    `{scaled}` gespeichert. `duration` ist eine Dauer nach ISO 8601 (`PT1M30.5S`, bis `P30D`, Tage, Stunden, Minuten,
    Sekunden mit bis zu drei Nachkommastellen) oder eine ganze Zahl Millisekunden; gespeichert wird sie in
    Millisekunden.
  - `timestamp`: Zeit des Werkzeugs nach ISO 8601 mit Zone (`2026-10-28T09:15:00.250Z`, `…+02:00`). Sie wird auf
    das Fenster der letzten 24 Stunden **geklemmt**: eine Zeit in der Zukunft gilt als jetzt, eine ältere als vor
    24 Stunden; ohne `timestamp` gilt jetzt. Daneben speichert Stundentakt die eigene Eingangszeit. Ein Werkzeug,
    das Ereignisse offline sammelt, meldet sie also binnen eines Tages.
  - Andere Felder werden nicht gelesen. Es gibt keinen Verweis auf eine Antwort: die meisten Ereignisse entstehen vor
    der Abgabe, und eine Abgabe wird ersetzt.
- `GET/PUT blocks/{block}/note`: `{note: string|null}`. Es ist die Notiz, die jede Person unter jedem Baustein
  führt; sie gehört ihr allein und ist nie eine Antwort.
- Ein Baustein eines **anderen** Werkzeugs ist `404 not_found`.
- **Link und öffentlich:** Ein per Link geteiltes oder öffentliches Medium, das Teilnahme annimmt, hat eine Zuweisung
  ohne Klasse; der Start nennt sie wie jede andere. Eine angemeldete Schüler:in (aus jeder Klasse) und eine
  Lehrer:in nehmen dort teil wie ein Gast, unter sich selbst (`me.role` ist `guest`). Die Lehrer:in der Schule des
  Mediums leitet sie (`teacher`).
- **Gäste** sind für ein Werkzeug nicht angemeldet: Sie bekommen kein Token (`/oauth/authorize` antwortet
  `error=access_denied&reason=guest_not_supported`), jede Route antwortet ohne Token `401 token_invalid`; ein
  Werkzeug speichert für sie nur auf dem Gerät.

## 5a Freie Daten (Records)

Was ein Werkzeug außerhalb einer Aufgabe für eine Person aufbewahrt (eigene Programme, Vokabeln, Einstellungen),
legt es als **Record** in einer **Datenart** (`collection`) ab. Kein Werkzeug legt Tabellen an; jede Datenart ist
ein Name, den das Werkzeug frei wählt: `[a-z0-9_-]`, 1 bis 64 Zeichen (ein anderer Name: `404 not_found`, beim
Anlegen `invalid`). Das Werkzeug ist immer das des Tokens, nie eines aus der Adresse: Werkzeug A erreicht keinen
Record von Werkzeug B, auch nicht mit dem Token derselben Person.

- **Record:** `{id, collection, data, schema, visibility, created_at, updated_at, owner}`. `id` ist die ULID.
  `data` ist ein JSON-Objekt oder eine Liste, höchstens 64 KB (Bytes des UTF-8-JSON). `schema` ist die
  Formatnummer des Werkzeugs (ganze Zahl ≥ 1, Standard 1): Stundentakt liest `data` nie und hebt keine alten
  Records an; das macht das Werkzeug beim Lesen. Zeiten sind ISO 8601 in UTC mit Mikrosekunden.
- **`owner`:** `{kind, alias, self}`; `kind` ist `student` oder `teacher`, `alias` bei einer Schüler:in ihr
  Pseudonym, bei einer Lehrer:in ihr Anzeigename („J. Muster“), nie eine E-Mail; `self` ist `true` für die eigene.
- **`GET …/records`:** `sort` = `-updated` (Standard), `updated`, `-created`, `created`; `page` (ab 1), `per_page`
  (Standard 50, höchstens 100). Antwort `{items, page, per_page, total}`. Ohne `scope` nur eigene Records;
  `scope=shared` nur Records anderer Personen dieses Werkzeugs, die die Person lesen darf.
- **`POST …/records`:** `{data, schema?, visibility?}` → `201` mit dem Record.
- **`PATCH …/records/{id}`:** `{data?, schema?, visibility?, updated_at}`. `updated_at` ist Pflicht und so zu senden,
  wie das Werkzeug es zuletzt gelesen hat; hat sich der Record seitdem geändert, `409 conflict` mit dem aktuellen
  Stand in `record`. Verglichen wird auf die Mikrosekunde, zwei Speicherungen in derselben Sekunde sind also
  verschieden. Was der Körper weglässt, bleibt.
- **`DELETE …/records/{id}`:** `204`.
- **Freigabe** (`visibility`, nur die Eigentümer:in setzt sie; jede Stufe schließt die vorige ein):
  - `private` (Standard): nur sie selbst.
  - `group`: wer mit ihr eine aktive Klasse teilt – die Schüler:innen und die Lehrer:innen der Klasse, auch das
    Elternteil in der Klasse seines Kindes („Meine Kinder“).
  - `team`: dazu, wer zu einem ihrer Teams gehört – die Lehrer:innen der Schule (bzw. des eigenen Bereichs) und
    die Schüler:innen der aktiven Klassen darin. Die Teams einer Schüler:in sind die ihrer aktiven Klassen.
  - `public`: jede:r mit der ULID, auch ohne Token über `GET records/{id}`. In `scope=shared` erscheint er nur
    für Personen, die über `group` oder `team` verbunden sind; die Liste ist kein öffentliches Verzeichnis.
  - Klassen im Papierkorb verbinden niemanden. Andere lesen nur; ändern oder löschen sie, `403 forbidden`.
  Ein Record, den die Person nicht lesen darf, ist `404 not_found` (nie `403`), damit sein Dasein nicht verraten wird.
- **Speicher:** Die Größe von `data` zählt gegen das Team, dessen Abo die Person trägt (Abschnitt 5b); Grenze und
  Verbrauch nennt `GET me` unter `entitlements.records`. Eine Schüler:in ohne aktive Klasse hat keinen Speicher:
  `403 no_storage`. Ist das Team voll, `413 quota_exceeded`.
- **Öffentlich ohne Token:** `GET /api/v1/tools/records/{id}` antwortet nur für `public`, sonst `404`; dieselbe
  Form, `owner.self` ist `false`. Gedrosselt je Adresse (120 je Minute).
- **Gäste** haben kein Token und damit keine Records.

## 5b Abo: `GET me`

```json
{
  "kind": "member",
  "alias": "Dachs Emil",
  "profile_url": "https://stundentakt.eu/me",
  "entitlements": {
    "plan": "pro",
    "plan_name": "Pro",
    "features": {"ai_pro_model": false},
    "ai": null,
    "records": {"limit_bytes": 50000000, "own_bytes": 1234, "record_max_bytes": 65536}
  }
}
```

- `kind`: `user` (Lehrer:in, Elternteil) oder `member` (Schüler:in, Kind).
- `alias`: der Name, den die Person außerhalb einer Klasse trägt: bei einer Schüler:in ihr Pseudonym, bei einer
  Lehrer:in ihr Anzeigename („J. Muster“). Nie ein echter Name einer Schüler:in, nie eine E-Mail, nie eine ID.
- `profile_url`: wo die Person sich in Stundentakt selbst verwaltet, je nach Art: Lehrer:in `/settings`, Schüler:in
  `/me`. Ein Werkzeug öffnet sie in einem neuen Tab (etwa „Profil bei Stundentakt ↗“), nie im eigenen Rahmen.
- `entitlements`: was das Abo freischaltet, ohne Preis, Team oder Abrechnung.
  - `plan`: `free`, `pro` oder `premium`; `plan_name` dessen Name in der Sprache der Anfrage.
  - `features`: Schalter des Plans als Map (`true` = freigeschaltet). `ai_pro_model`: das bessere KI-Modell. Ein
    Schalter, den ein Plan sperrt, steht mit `false` darin; fehlt ein Schalter, ist er offen.
  - `ai`: das KI-Kontingent der Lehrer:in im laufenden Monat, `{monthly_tokens, remaining_tokens}` (Anzahl Tokens).
    Eine Schüler:in hat keines (`null`). Ein Werkzeug ruft selbst keine KI auf; es liest hier nur, was übrig ist.
  - `records`: Speicher der freien Daten (Abschnitt 5a) in Bytes: `limit_bytes` des Teams, das sich alle seine
    Mitglieder teilen (`0`: kein Speicher), `own_bytes` der eigenen Records über alle Werkzeuge, `record_max_bytes`
    je Record. Den Verbrauch der anderen nennt Stundentakt nie; ist das Team voll, antwortet das Schreiben mit
    `413 quota_exceeded`.

**Wessen Abo?** Ein Abo gehört immer einem Team (eigener Bereich einer Lehrer:in oder Schule).

| Person | trägt das Abo von |
|---|---|
| Lehrer:in | dem besten ihrer Teams: eigener Bereich und ihre Schulen |
| Schüler:in | dem besten der Teams ihrer aktiven Klassen (Klassen im Papierkorb zählen nicht) |
| Kind eines Elternteils („Meine Kinder“) | dem eigenen Bereich des Elternteils, denn dort liegt die Klasse des Kindes |
| Gast | niemandem: nur das kostenlose Angebot, und ohne Token ohnehin kein `me` |

„Das beste“ ist der Plan mit dem höchsten Rang in der Reihenfolge der Konfiguration (`free` < `pro` <
`premium`). Bei gleichem Plan gewinnt ein eigener Bereich vor einer Schule, danach das älteste Team. Dasselbe Team
zählt den Speicher der Records.

## 5c Meine Kurse und Links: `GET me/assignments`, `GET links/resolve`

Beide antworten mit derselben Form je Zuweisung (`ToolAssignment` in der OpenAPI-Beschreibung):

```json
{
  "assignment": "01k…",
  "role": "student",
  "document": {"ulid": "01k…", "name": "Brüche üben", "type": "page"},
  "group": {"name": "8b"},
  "mode": "interact",
  "open_from": null,
  "closes_at": "2026-11-04T23:59:00+01:00",
  "open": true,
  "progress": {"done": 1, "total": 3, "blocks": [{"ulid": "01k…", "done": true}]},
  "last_activity": "2026-10-28T14:05:12+01:00",
  "blocks": ["01k…"]
}
```

- `role`: `teacher` (leitet die Klasse), `student` oder `guest` (auf dem Link), wie `me.role` in `GET assignments/{a}`.
- `group`: nur der Name der Klasse, nie ihre Mitglieder, ihr Code oder eine Zahl; `null` auf dem Link.
- `open`: ob die Klasse jetzt Antworten annimmt (Fenster und Modus). Die Lehrer:in der Klasse darf auch außerhalb.
- `progress`: der eigene Fortschritt wie in `GET assignments/{a}`; für die Lehrer:in der Klasse `null` (sie zählt nie
  als Klasse und liest die Auswertung in Stundentakt). Bei einem Kurs die Summe: die Aufgaben des Kurses selbst und
  jedes Medium aus `lessons` (mit `progress`) einmal, auch wenn es in mehreren Stunden steht; `blocks` nennt alle.
  „3 von 7 abgegeben“ ist also `progress.done` von `progress.total`.
- `last_activity`: wann die Person hier zuletzt abgegeben, einen Zwischenstand gespeichert oder **dieses** Werkzeug
  ein Ereignis gemeldet hat (ISO 8601); bei einem Kurs auch in den Medien aus `lessons`. `null`, solange nichts davon
  geschah, und für die Lehrer:in der Klasse.
- `blocks`: die ULIDs der Bausteine dieses Werkzeugs im Medium, die die Person sieht (mit ihnen startet das Werkzeug
  wie mit `launch.block`).
- `lessons` (nur bei einem Kurs): die Stunden, die auf ein Medium mit einem Baustein dieses Werkzeugs verweisen,
  `[{ulid, topic, media: [{ulid, name, type, assignment, progress?, blocks}]}]`. `medium` wie in `content`, dazu `blocks`
  dieses Mediums. Eine Stunde, die noch bevorsteht, zeigt der Klasse keine Medien und fehlt dann.

**`GET me/assignments`** (`?page=1&per_page=50`, höchstens 100): `{items, page, per_page, total}`.

- Enthält nur Zuweisungen, deren Medium einen Baustein **dieses** Werkzeugs trägt (auch einen, den die Klasse
  ergänzt hat), und Kurse, deren Stunden auf solche Medien verweisen. Ein Werkzeug erfährt nichts von den Aufgaben
  anderer Werkzeuge.
- Schüler:in: ihre aktiven Klassen, solange die Klasse die Zuweisung sieht (Sichtbarkeitsfenster), und Links
  geteilter Medien, auf denen sie schon abgegeben oder einen Zwischenstand gespeichert hat.
- Lehrer:in: die Klassen, die sie unterrichtet (`role: teacher`, auch außerhalb des Fensters), und Links, auf denen sie
  mitgemacht hat. Klassen im Papierkorb fehlen.
- Reihenfolge: nach Frist (`closes_at`, früheste zuerst, ohne Frist zuletzt), dann die neueste Zuweisung zuerst.

**`GET links/resolve?url=…`**: die Zuweisung, die die Person über diese Adresse erreicht.

- `url`: eine Adresse dieser Instanz, absolut (nur die eigene Origin oder die Kurzlink-Domain) oder relativ (`/m/…`),
  oder ein Code allein (`ABC-DEF`, Groß- und Kleinschreibung und Bindestrich egal). Erkannt werden `/d/{medium}`,
  `/m/{medium}`, `/m/{medium}/class/{klasse}`, `/a/{zuweisung}`, `/stage/medium/{medium}`, `/stage/block/{baustein}`,
  `/stage/slides/{baustein}`, `/live/{runde}` und `/live/{runde}/play` sowie Kurzlinks (`/{code}`) eines Mediums,
  einer Zuweisung oder einer Live-Runde.
- Aufgelöst wird wie in der App: ein Medium führt in die Klasse der Person, die es hat (eine in der Adresse genannte
  Klasse zuerst, sonst eine, die es jetzt sieht, die neueste zuerst); hat keine ihrer Klassen es, auf den Link eines
  per Link geteilten oder öffentlichen Mediums, das Teilnahme annimmt (`role: guest`). Eine Zuweisung oder Runde, an
  der die Person nicht teilnimmt, führt wie in der App auf ihr Medium.
- Ein Klassencode nennt eine Klasse, kein Medium: `404`. Ein Werkzeug listet ihre Aufgaben mit `GET me/assignments`.
- `404 not_found` für alles, was die Person nicht erreicht, was keinen Baustein dieses Werkzeugs (und als Kurs keine
  Stunde mit einem solchen Medium) hat, für eine fremde Adresse und für Unsinn. Ob es das Medium gibt, verrät die
  Antwort nie. Ohne `url`: `422 invalid`.

## 6 Fehler

Jeder Fehler ist `{message, reason}` (bei `invalid` zusätzlich `errors` je Feld, bei `not_open` `detail` und
`errors`, bei `conflict` `block` bzw. `record`). Maßgeblich ist `reason`.

| `reason` | Status | Ursache | wer behebt es |
|---|---|---|---|
| `token_expired` | 401 | Zugriffstoken abgelaufen | Werkzeug: erneuern (`refresh_token`) |
| `token_revoked` | 401 | widerrufen: abgemeldet, durch Erneuern ersetzt, jemand anderes hat sich im Browser angemeldet | Werkzeug: still neu anmelden (`prompt=none`), sonst die Person |
| `token_invalid` | 401 | kein Token, fremdes oder kaputtes Token, Token eines gelöschten Eintrags oder einer gelöschten Person | Werkzeug: neu anmelden |
| `wrong_scope` | 403 | Lese-Token auf einer schreibenden Route | Werkzeug: mit `tools:write` anmelden |
| `wrong_origin` | 403 | Anfrage kommt nicht von der Origin der `launch_url` | Anbieter: Adresse am Eintrag prüfen |
| `tool_unavailable` | 403 | Eintrag gesperrt oder gelöscht | Betreiber bzw. Schule, die ihn eingetragen hat |
| `forbidden` | 403 | die Person darf das hier nicht (keine Teilnahme, fremde Klasse, fremder Record) | niemand; das Werkzeug zeigt es |
| `guest_not_supported` | 403 | ein Gast ist für Werkzeuge nicht angemeldet (Rücksprung von `/oauth/authorize`; zweite Linie der API) | niemand; das Werkzeug speichert lokal |
| `no_storage` | 403 | eine Schüler:in ohne aktive Klasse hat keinen Speicher für Records | Lehrer:in: Schüler:in in eine Klasse aufnehmen |
| `not_found` | 404 | nichts dieses Namens oder nichts, was dieses Werkzeug besitzt | Werkzeug: Adresse prüfen |
| `withdrawn` | 404 | die Antwort einer Durchsicht gibt es nicht mehr (zurückgezogen oder entfernt) | niemand; das Werkzeug zeigt es |
| `conflict` | 409 | Aufgabe oder Record wurde seit `updated_at` geändert; `block` bzw. `record` ist der aktuelle Stand | Werkzeug: aktuellen Stand übernehmen oder zusammenführen |
| `too_large` | 413 | `state`, `task`, `hidden` oder `data` eines Records über 64 KB | Werkzeug: weniger speichern |
| `quota_exceeded` | 413 | der Speicher für Records des Teams ist voll | Person: Records löschen; Team: größeres Abo |
| `invalid` | 422 | Körper passt nicht; `errors` nennt die Felder | Werkzeug |
| `not_open` | 422 | die Klasse nimmt jetzt keine Antwort an; `detail`: `not_yet` (noch nicht offen), `closed` (Frist vorbei oder nicht mehr sichtbar), `wrong_mode` („Nur ansehen“ oder eine Live-Runde hält den Baustein zurück) | Lehrer:in der Klasse: Fenster oder Modus |
| `too_many_requests` | 429 | zu viele Aufrufe (600 je Person und Minute; öffentlicher Record 120 je Adresse und Minute) | Werkzeug: `Retry-After` Sekunden warten |
| `maintenance` | 503 | Stundentakt wird gewartet | niemand; das Werkzeug wartet `Retry-After` Sekunden und versucht es erneut |

`/oauth/token` antwortet mit den Fehlern nach RFC 6749 (`{error, error_description}`, z. B. `invalid_grant`),
nur in der Wartung mit `maintenance` wie oben.

## 7 Browser-Regeln

- **CORS:** Antwort nur für die Origin der `launch_url` (`Access-Control-Allow-Origin` genau diese, nie `*`),
  **ohne** Cookies (`credentials: 'omit'`). Der Vorab-Aufruf (`OPTIONS`) braucht kein Token. Jede Antwort,
  auch ein 401, ein 429 und die Wartung, trägt die CORS-Kopfzeilen und `Access-Control-Expose-Headers: Retry-After`,
  damit das Werkzeug die Wartezeit lesen kann. Eine andere Origin erhält `wrong_origin`. `/oauth/token` antwortet
  zusätzlich den Origins der Rücksprungadressen.
- **Cache:** Jede Antwort der Werkzeug-API trägt `Cache-Control: no-store`, Fehler eingeschlossen; Antworten sind
  immer die einer Person.
- **Wartung:** Während Stundentakt gewartet wird (`php artisan down`), antworten `/api/v1/tools/*` und
  `/oauth/token` mit `503 {message, reason: "maintenance"}`, `Retry-After` in Sekunden (`--retry` der Wartung,
  sonst 300) und den CORS-Kopfzeilen; der Vorab-Aufruf antwortet weiter. Die Seiten der App zeigen ihre
  Wartungsseite wie immer.
- **Rahmen:** Stundentakt erlaubt die Origin des Werkzeugs in `frame-src`, nur auf Seiten, die den Baustein zeigen.
- **Sandbox:** Der Rahmen trägt `allow-scripts allow-same-origin allow-forms allow-modals allow-popups
  allow-popups-to-escape-sandbox allow-downloads`, keinen Zugriff auf Stundentakt selbst.

## 8 Nachricht `height` und Abmelden

Das Werkzeug meldet seine Höhe an `window.parent`:

```js
parent.postMessage({ source: 'stundentakt-lernobjekt', v: 1, type: 'height', height: 640 }, '*');
```

Nur `height` (px, > 0, höchstens 20000) wird beachtet, jede andere Nachricht verworfen. Stundentakt glaubt
sie nur aus dem eigenen Rahmen und von der Origin des Werkzeugs. Tokens reisen nie per Nachricht.

Hat das Werkzeug eine Abmelden-Funktion, ruft es `POST logout` auf: das widerruft Zugriffs- und
Erneuerungstoken der Person in allen Werkzeugen. Danach vergisst es seine Tokens. Das Abmelden in Stundentakt
widerruft sie ebenso; das Werkzeug erfährt es beim nächsten Aufruf als `token_revoked`.

### Anmelden und Abmelden im eigenen Fenster

Anmelden geht immer über `/oauth/authorize` (Abschnitt 4); ist niemand angemeldet, führt Stundentakt über
`/login?next=<Authorize-Adresse>` und zurück. `next` übersteht jeden Zwischenschritt (E-Mail-Bestätigung,
Einwilligung, Klassencode → PIN, Anmeldekarte → PIN, beste.schule). Erlaubt sind Pfade von Stundentakt und
**eingetragene Rücksprungadressen** eines nicht gesperrten Werkzeugs (gleiche Origin und gleicher Pfad, die
Query ist frei); alles andere wird verworfen. Wer nach dem Abmelden auf eine andere Seite will, trägt sie als
Rücksprungadresse ein.

**Übergabeseite `GET /continue?next=…`:** Die Seiten von Stundentakt tragen `form-action 'self'`, und das gilt für
jede Weiterleitung, der ein abgeschicktes Formular folgt. Endet ein Formular (Abmelden, PIN, Einwilligung,
E-Mail-Bestätigung erneut senden, Klasse hinzufügen) oder die Rückkehr von beste.schule bei einer Werkzeug-Adresse
oder bei `/oauth/authorize`, leitet Stundentakt darum erst auf diese eigene Seite. Sie prüft `next` erneut wie oben
(fremde Adresse oder inzwischen gesperrtes Werkzeug: Startseite) und navigiert per `meta refresh` dorthin, mit Link
als Rückfall; das ist eine neue Navigation, kein Formular. Für das Werkzeug ändert sich nichts: am Ende steht
dieselbe Adresse mit Code bzw. `error`. Ein `GET` (z. B. `/logout?next=…` ohne Anmeldung) leitet direkt weiter.

| Adresse | Wirkung |
|---|---|
| `GET /login?next=…` | Anmeldeseite mit allen Wegen (Konto, beste.schule, Klassencode, Anmeldekarte) |
| `GET /login/beste-schule?next=…` | geht sofort zu beste.schule; Lehrer:in und Schüler:in, das Konto entscheidet |
| `GET /logout?next=…` | fragt nach und meldet erst mit dem Knopf ab (`POST /logout`), danach `next` |

Lehnt beste.schule ab oder bricht die Person ab, kommt sie mit `error=access_denied&reason=…` auf `next`
zurück: `cancelled` (abgebrochen), `failed` (technischer Fehler), `function_account` (Funktionskonto),
`unknown_account` (weder Lehrer:in noch Schüler:in), `email_missing`, `email_unconfirmed` (Adresse ohne
Bestätigung, Konto nicht verknüpft), `no_class` (Schüler:in ohne gekoppelte Klasse).

## 9 Grenzen

| Grenze | Wert |
|---|---|
| `state`, `task`, `hidden` | je 64 KB (65 536 Bytes des JSON) |
| Record (`data`) | 64 KB (65 536 Bytes des UTF-8-JSON) |
| Records je Team | 50 MB (50 000 000 Bytes, Summe aller `data`; je Abo einstellbar, siehe `entitlements.records`) |
| Datenart (`collection`) | 1–64 Zeichen `[a-z0-9_-]` |
| Records je Seite | 50 Stück, höchstens 100 |
| Zuweisungen je Seite (`me/assignments`) | 50 Stück, höchstens 100 |
| `url` in `links/resolve` | 2 048 Zeichen |
| Ereignisse je Aufruf | 100 Stück; `verb` ≤ 40 Zeichen, `code` ≤ 80 Zeichen, `result` ≤ 2 KB (Bytes des JSON) |
| `timestamp` eines Ereignisses | geklemmt auf die letzten 24 Stunden |
| Notiz | 10 000 Zeichen |
| Aufrufe | 600 je Person und Minute |
| öffentlicher Record ohne Token | 120 Aufrufe je Adresse und Minute |
| Dateien | zählen gegen den Speicher der Schule der Klasse |
| Zugriffstoken | 15 Minuten (`TOOL_ACCESS_TOKEN_MINUTES`) |
| Erneuerungstoken | 30 Minuten ohne Erneuern (`TOOL_REFRESH_TOKEN_MINUTES`, Standard `SESSION_LIFETIME`) |
| Bildadresse in `images` | 5 Minuten gültig |
| Rücksprungadressen | 10 Stück je Eintrag |
| `height` | 1 bis 20 000 px |
| `Retry-After` in der Wartung | 300 Sekunden, wenn die Wartung keine eigene Zeit nennt |

## 10 Daten und Datenschutz

- Das Werkzeug sieht nur das Pseudonym der Schüler:in.
- `state` ist Arbeitsdaten des Werkzeugs: Es steht in keinem Export, keiner Auswertung und erreicht keine
  KI. Die Lehrer:in liest es nur im Modus `review`.
- Es gibt **keinen Prüfdienst**: Lösungen dürfen im Werkzeug selbst liegen. Der versteckte Teil (`hidden`) ist
  keine Lösung im Sinne von Stundentakt und wird nur der Autor:in und dem Werkzeug in ihrer Hand gezeigt.
- Zwischenstand, Antwort, Notiz und Ereignisse gehören der Person. Wer Konto, Mitglied oder Klasse löscht,
  löscht sie mit.
- Records gehören der Person: privat, solange sie sie nicht freigibt; sie gehen mit ihrem Konto bzw. ihrem
  Mitglied und mit dem Werkzeug-Eintrag. Sie stehen in keinem Export, keiner Auswertung und erreichen nie eine KI
  oder die MCP-Schnittstelle.
- Eine mitmachende Lehrer:in zählt nie als Klasse; ihre Antworten und Ereignisse fehlen in Auswertung, Export
  und KI.
- **Auswertung je Aufgabe:** Die Lehrer:innen der Klasse (und nur sie) sehen in der Auswertung der Zuweisung unter
  jedem Werkzeug-Baustein, wie viele Schüler:innen etwas gemeldet haben, je Verb und je Code „x von y“ samt Anzahl
  und, wenn das Werkzeug `run` meldet, wie oft die Abgebenden vor ihrer Abgabe im Schnitt ausgeführt haben. Nur
  Zahlen und die Wörter des Werkzeugs, keine Namen; je Zuweisung, nie über Klassen hinweg.
- Ereignisse haben noch keine eigene Aufbewahrungsfrist: sie gehen mit Person, Werkzeug-Eintrag, Zuweisung und
  Baustein.
