feat(docs): mkdocs-style documentation site served at /docs

Full documentation hub replacing the release-notes-only view: - Handbook pages (docs/handbook) for all features and admin/betrieb - API reference generated from lib/api-spec/openapi.yaml via scripts/src/generate-docs.mjs (replaces sync-release-docs.mjs): endpoints, schemas/fields, search index, per-release snapshots - mkdocs layout: sidebar nav, right TOC with scrollspy, search overlay, version dropdown, repo link - FieldHelp (?) buttons in forms linking to reference field docs - v0.7.0 release notes backfilled, v0.8.0 release notes added
2026-08-03 22:15:54 +02:00
parent 520f917723
commit 6c92b6358d
29 changed files with 7545 additions and 264 deletions
@@ -1,38 +1,51 @@
-# Release-Dokumentation
+# Dokumentation (Handbuch, API-Referenz, Release-Notes)

-Jeder Release hat eine version-gebundene Dokumentation unter
-`docs/releases/`. Die Dokumentation wird öffentlich in der App unter
-`/docs` (Index) und `/docs/<version>` (Detail) angezeigt.
+Die App zeigt unter `/docs` eine MkDocs-artige Doku-Seite mit drei Bereichen:
+
+- **Handbuch** (`docs/handbook/*.md`) — von Hand gepflegte Anleitungen
+- **API-Referenz** (`lib/api-spec/openapi.yaml`) — automatisch generierte
+  Endpunkte & Datenfelder (Schema-Detailseiten mit Feld-Ankern; die `?`-Icons
+  in Formularen verlinken auf diese Felder)
+- **Release-Notes** (`docs/releases/vX.Y.Z.md`) — pro Release

 ## Struktur

+- `docs/handbook/` — Handbuch-Seiten mit Frontmatter (`title`, `order`)
 - `docs/releases/TEMPLATE.md` — Vorlage für neue Releases
- `docs/releases/vX.Y.Z.md` — Dokumentation pro Release (eine Datei je Version)
+- `docs/releases/vX.Y.Z.md` — Notes pro Release
+- `docs/releases/vX.Y.Z/reference.json` — API-Snapshot der jeweiligen Version

-## Inhalt
+## Generator

-Pro Release wird abgedeckt (kombiniert):
+`scripts/src/generate-docs.mjs` wird beim Frontend-Build (und `dev`) automatisch
+ausgeführt und schreibt die Artefakte nach `artifacts/toolrate/public/docs/`:

- **Changelog:** Neue Features, Fixes & Verbesserungen
- **API-Änderungen:** Neue/geänderte/entfernte Endpunkte (Delta zur Vorversion)
- **Betrieb / Upgrade:** Env-Vars, DB-Migrationen, Breaking Changes
+- `reference.json` (aktuelle API), `search.json` (Suchindex),
+  `index.json` (Releases), `handbook/*.md` + `handbook/index.json`
+- `releases/vX.Y.Z.md` und `versions/vX.Y.Z.json` (API-Snapshots alter Versionen)
+
+Manuell aufrufbar:
+
+```sh
+node scripts/src/generate-docs.mjs                  # Build-Modus
+node scripts/src/generate-docs.mjs --snapshot v0.9.0   # Snapshot für neue Version
+```

 ## Workflow beim Release

 1. **Version taggen** wie bisher (`git tag vX.Y.Z`, CI baut und deployed).
-2. **`docs/releases/vX.Y.Z.md` anlegen** — Vorlage aus
-   `TEMPLATE.md` kopieren. Entwurf aus der Git-Historie seit dem letzten Tag
-   ableiten:
+2. **`docs/releases/vX.Y.Z.md` anlegen** — Vorlage aus `TEMPLATE.md` kopieren,
+   Entwurf aus der Git-Historie ableiten:
   ```sh
   git log --oneline vX.Y.Z-1..vX.Y.Z
   ```
-   (Funktions-/Fix-Commits in die passenden Abschnitte übernehmen, API-Delta
-   anhand `lib/api-spec/openapi.yaml` prüfen.)
-3. **Committen & pushen.** Der Sync-Schritt (`scripts/sync-release-docs.mjs`)
-   kopiert die Markdown-Dateien beim Frontend-Build automatisch nach
-   `artifacts/toolrate/public/docs/` und generiert `index.json`. Dadurch sind
-   die Releases im Deployment als `/docs/...` verfügbar.
+   (API-Delta anhand `lib/api-spec/openapi.yaml` prüfen.)
+3. **API-Snapshot erzeugen:** `node scripts/src/generate-docs.mjs --snapshot vX.Y.Z`
+   erzeugt `docs/releases/vX.Y.Z/reference.json`.
+4. **Committen & pushen.** Der Build kopiert die Dokumentation automatisch nach
+   `artifacts/toolrate/public/docs/` und generiert `index.json`.

-> Hinweis: `index.json` und die kopierten Dateien unter
-> `artifacts/toolrate/public/docs/` sind Build-Artefakte und werden bei jedem
-> Build neu generiert — nicht von Hand bearbeiten.
+> Hinweis: Alle Dateien unter `artifacts/toolrate/public/docs/` sind
+> Build-Artefakte und werden bei jedem Build neu generiert — nicht von Hand
+> bearbeiten. Einzige Quellen sind `docs/handbook/`, `docs/releases/` und
+> `lib/api-spec/openapi.yaml`.
@@ -0,0 +1,61 @@
+---
+title: Administration & Papierkorb
+order: 7
+---
+
+# Administration & Papierkorb
+
+Diese Bereiche sind nur für **Administrator:innen** sichtbar und nutzbar.
+
+## Nutzerverwaltung
+
+Unter **Admin → Nutzer** kannst du:
+
+- **Lokale Nutzer anlegen** (Benutzername, Passwort, E-Mail, Rolle, Tier).
+- **Rollen/Tier ändern** (`admin`/`user`, `free`/`premium`/`enterprise`).
+- **Passwörter zurücksetzen** (nur lokale Nutzer).
+- **Nutzer löschen**.
+
+Zugehörige Endpunkte (Admin-only):
+
+- [`GET /users`](/docs/reference/endpoints/users#listusers)
+- [`POST /users`](/docs/reference/endpoints/users#createuser)
+- [`PATCH /users/{id}`](/docs/reference/endpoints/users#updateuser)
+- [`DELETE /users/{id}`](/docs/reference/endpoints/users#deleteuser)
+- [`PATCH /users/{id}/password`](/docs/reference/endpoints/users#setuserpassword)
+
+## Audit-Log
+
+Das **Audit-Log** protokolliert sicherheitsrelevante Änderungen (wer hat wann
+was geändert). Es ist über
+[`GET /audit-logs`](/docs/reference/endpoints/audit#listauditlogs) abrufbar und
+filterbar nach Entitätstyp, Entitäts-ID und Limit.
+
+## Papierkorb (Trash)
+
+Tools werden nicht sofort gelöscht, sondern zuerst **soft gelöscht** (in den
+Papierkorb verschoben):
+
+- **Liste:** [`GET /tools/trash`](/docs/reference/endpoints/tools#listtrashedtools)
+- **In den Papierkorb verschieben:** [`POST /tools/trash`](/docs/reference/endpoints/tools#trashtools)
+- **Wiederherstellen:** [`POST /tools/trash/restore`](/docs/reference/endpoints/tools#restoretools)
+- **Endgültig löschen (einzeln):** [`DELETE /tools/trash`](/docs/reference/endpoints/tools#deletetrashedtools)
+- **Papierkorb leeren:** [`POST /tools/trash/empty`](/docs/reference/endpoints/tools#emptytrash)
+
+> Die Aufbewahrungsfrist des Papierkorbs (in Tagen) ist im
+> [`VersionInfo`](/docs/reference/schemas/versioninfo)-Schema als
+> `trashRetentionDays` verfügbar.
+
+## Felder im Überblick
+
+### User
+
+| Feld | Typ | Bedeutung |
+| --- | --- | --- |
+| `id` | integer | Eindeutige Nutzer-ID. |
+| `username` | string | Anmeldename. |
+| `email` | string? | E-Mail-Adresse. |
+| `role` | string | `admin` oder `user`. |
+| `tier` | string | `free`, `premium` oder `enterprise`. |
+| `authProvider` | string | `local` oder `oidc`. |
+| `createdAt` | date-time | Erstellungszeitpunkt. |
@@ -0,0 +1,37 @@
+---
+title: Analytics
+order: 6
+---
+
+# Analytics
+
+Der Bereich **Analytics** fasst die Plattform-Statistiken zusammen — für alle
+Nutzer:innen ohne Einschränkung sichtbar.
+
+## Übersicht
+
+| Widget | Quelle (Endpunkt) | Inhalt |
+| --- | --- | --- |
+| **Plattform-Kennzahlen** | [`GET /analytics/summary`](/docs/reference/endpoints/analytics#getanalyticssummary) | Gesamtzahl Tools, Bewertungen, Durchschnittswerte, Kategorienzahl. |
+| **Top-Tools** | [`GET /analytics/top-tools`](/docs/reference/endpoints/analytics#gettoppertools) | Bestbewertete Tools nach wählbarer Metrik (Nützlichkeit, Bedienbarkeit, kombiniert). |
+| **Nach Kategorie** | [`GET /analytics/by-category`](/docs/reference/endpoints/analytics#getanalyticsbycategory) | Kennzahlen je Kategorie. |
+| **Verteilung** | [`GET /analytics/rating-distribution`](/docs/reference/endpoints/analytics#getratingdistribution) | Verteilung der Bewertungswerte (optional je Tool). |
+
+## Datenfelder
+
+### AnalyticsSummary
+
+| Feld | Typ | Bedeutung |
+| --- | --- | --- |
+| `totalTools` | integer | Anzahl aller Tools. |
+| `totalRatings` | integer | Anzahl aller Bewertungen. |
+| `avgUsefulness` | number? | Durchschnittliche Nützlichkeit. |
+| `avgUsability` | number? | Durchschnittliche Bedienbarkeit. |
+| `avgCombined` | number? | Durchschnitt kombinierter Wert. |
+| `categoriesCount` | integer | Anzahl der Kategorien. |
+| `mostRatedTool` | ToolWithStats | Das meistbewertete Tool. |
+
+Vollständige Feldlisten: [`AnalyticsSummary`](/docs/reference/schemas/analyticssummary),
+[`TopToolEntry`](/docs/reference/schemas/topptoolentry),
+[`CategoryStats`](/docs/reference/schemas/categorystats),
+[`RatingDistribution`](/docs/reference/schemas/ratingdistribution).
@@ -0,0 +1,45 @@
+---
+title: Bewertungen
+order: 4
+---
+
+# Bewertungen
+
+Bewertungen sind das Herz von toolr: Sie zeigen, wie nützlich und wie gut
+bedienbar ein Tool in den Augen der Community ist.
+
+## Wie funktioniert die Bewertung?
+
+Auf der Detailseite eines Tools vergibst du zwei Werte (1–5 Sterne):
+
+- **Nützlichkeit** — Wie gut löst das Tool sein Kernproblem?
+- **Bedienbarkeit** — Wie einfach ist es zu bedienen?
+
+Optional kannst du einen **Kommentar** und deinen **Namen** hinterlassen. Die
+Eingabefelder entsprechen dem Schema
+[`RatingInput`](/docs/reference/schemas/ratinginput).
+
+## Was passiert mit meiner Bewertung?
+
+- Deine Bewertung wird sofort gespeichert und in den Durchschnittswerten des
+  Tools berücksichtigt.
+- Jede Bewertung ist über [`GET /tools/{id}/ratings`](/docs/reference/endpoints/ratings#listtoolratings)
+  abrufbar.
+- Der **Rating-Verlauf** über die Zeit ist über
+  [`GET /tools/{id}/rating-history`](/docs/reference/endpoints/tools#gettoolratinghistory)
+  einsehbar (grafisch auf der Detailseite).
+
+## Datenfelder
+
+Eine Bewertung besteht aus diesen Feldern
+([`Rating`](/docs/reference/schemas/rating)):
+
+| Feld | Typ | Bedeutung |
+| --- | --- | --- |
+| `id` | integer | Eindeutige ID der Bewertung. |
+| `toolId` | integer | ID des bewerteten Tools. |
+| `usefulness` | integer (1–5) | Nützlichkeitsbewertung. |
+| `usability` | integer (1–5) | Bedienbarkeitsbewertung. |
+| `comment` | string? | Optionaler Kommentar. |
+| `reviewerName` | string? | Optionaler Anzeigename des Bewerters. |
+| `createdAt` | date-time | Zeitpunkt der Bewertung. |
@@ -0,0 +1,60 @@
+---
+title: Datenmodell & Felder
+order: 8
+---
+
+# Datenmodell & Felder
+
+Dieses Handbuch erklärt die zentralen Objekte von toolr auf verständliche
+Weise. Die **vollständige, maschinell generierte Feld-Referenz** findest du in
+der [Referenz](/docs/reference/schemas/tool) — dort sind alle Typen, Pflicht-
+angaben und Constraints der aktuellen Version dokumentiert.
+
+> Die Referenz ist **versionsgebunden**: Über das Versions-Dropdown oben
+> kannst du ältere API-Stände einsehen.
+
+## Die wichtigsten Objekte
+
+### Tool
+
+Ein Tool ist der zentrale Eintrag im Katalog
+([Feld-Referenz](/docs/reference/schemas/tool)):
+
+| Feld | Bedeutung |
+| --- | --- |
+| `id` | Eindeutige ID. |
+| `name` | Anzeigename. |
+| `description` | Kurzbeschreibung. |
+| `category` | Kategorie-Zuordnung. |
+| `websiteUrl` / `iconUrl` | Offizielle Website bzw. Logo-Link (optional). |
+| `createdBy` | Nutzer, der das Tool angelegt hat (optional). |
+| `features` / `tags` | Listen von Schlüsselfähigkeiten bzw. Schlagwörtern. |
+| `createdAt` / `updatedAt` | Zeitstempel. |
+| `deletedAt` / `deletedBy` | Soft-Delete-Informationen (Papierkorb). |
+
+> **ToolWithStats** erweitert `Tool` um die Aggregatwerte `ratingCount`,
+> `avgUsefulness`, `avgUsability` und `avgCombined` (siehe
+> [Feld-Referenz](/docs/reference/schemas/toolwithstats)).
+
+### Rating
+
+Eine Bewertung (`Rating`) besteht aus `usefulness` und `usability` (jeweils
+1–5) sowie optionalem Kommentar und Bewerternamen. Details unter
+[Bewertungen](/docs/handbook/bewertungen).
+
+### User / AuthUser
+
+- **User** (Admin-Sicht): `id`, `username`, `email`, `role`, `tier`,
+  `authProvider`, `createdAt` — siehe [Administration](/docs/handbook/administration).
+- **AuthUser** (Eigenansicht): `sub`, `email`, `name`, `preferredUsername`,
+  `role`, `tier`, `entitlements`, `isLocal`.
+
+### VersionInfo
+
+`GET /version` liefert `version`, `commitSha`, `buildDate` und
+`trashRetentionDays` (siehe [Feld-Referenz](/docs/reference/schemas/versioninfo)).
+
+## Referenz selber durchsuchen
+
+Nutze das **Suchfeld** in der Doku-Seitenleiste: Es durchsucht Handbuch,
+Endpunkt- und Feldbeschreibungen und springt direkt zum passenden Anker.
@@ -0,0 +1,54 @@
+---
+title: Erste Schritte
+order: 2
+---
+
+# Erste Schritte
+
+Diese Seite führt dich durch die wichtigsten Abläufe in toolr — vom ersten
+Besuch bis zum Anlegen und Bewerten eines Tools.
+
+## 1. Anmelden
+
+Die meisten Aktionen (Tool anlegen, bewerten, Watchlist) erfordern ein
+Konto. Klicke oben rechts auf **Anmelden**. Je nach Konfiguration der Instanz
+hast du zwei Möglichkeiten:
+
+- **Lokale Konten:** Benutzername + Passwort. Der Zugang wird von einem Admin
+  angelegt (siehe [Administration](/docs/handbook/administration)).
+- **OIDC (SSO):** Anmelden mit dem konfigurierten Identitätsanbieter.
+
+Welcher Modus aktiv ist, steht im [Endpunkt
+`GET /auth/mode`](/docs/reference/endpoints/auth#getauthmode).
+
+## 2. Tools finden
+
+Öffne den Bereich **Tools durchsuchen**:
+
+- **Suchen** — Volltextsuche über Name & Beschreibung.
+- **Filtern** — nach Kategorie, Tags und Features; zusätzlich
+  Mindestbewertung (`minRating`).
+- **Sortieren** — nach Aktualität, Top-Bewertung, meistbewertet, Name
+  (auf-/absteigend) oder letztem Update.
+
+Die Such-, Filter- und Sortierparameter entsprechen den Query-Parametern von
+[`GET /tools`](/docs/reference/endpoints/tools#listtools).
+
+## 3. Tool anlegen
+
+Gehe auf **Tool hinzufügen** und fülle das Formular aus. Details zu jedem Feld
+findest du im [Handbuch "Tool anlegen"](/docs/handbook/tool-anlegen) und in der
+[Feld-Referenz](/docs/reference/schemas/toolinput).
+
+## 4. Bewerten
+
+Auf der Detailseite eines Tools kannst du **Nützlichkeit** und
+**Bedienbarkeit** (jeweils 1–5) vergeben und optional einen Kommentar
+hinterlassen. Deine Bewertung fließt sofort in die Statistiken ein.
+
+## 5. Weiterführend
+
+- [Tools vergleichen](/docs/handbook/vergleichen)
+- [Watchlist](/docs/handbook/watchlist)
+- [Analytics](/docs/handbook/analytics)
+- [Administration & Papierkorb](/docs/handbook/administration)
@@ -0,0 +1,50 @@
+---
+title: Überblick
+order: 1
+---
+
+# Willkommen bei toolr
+
+toolr ist eine Plattform zum **Entdecken, Bewerten und Vergleichen von
+Entwicklungstools**. Nutzer:innen pflegen einen gemeinsamen Katalog von Tools,
+vergeben Bewertungen (Nützlichkeit & Bedienbarkeit) und nutzen Statistiken, um
+die richtige Wahl zu treffen.
+
+## Was kannst du mit toolr tun?
+
+| Funktion | Beschreibung | Sichtbarkeit |
+| --- | --- | --- |
+| **Tools durchsuchen** | Katalog filtern, sortieren und durchsuchen | Alle |
+| **Tool anlegen** | Neues Tool mit Beschreibung, Kategorie, Features & Tags eintragen | Angemeldet |
+| **Bewerten** | Nützlichkeit & Bedienbarkeit (1–5) plus Kommentar vergeben | Angemeldet |
+| **Vergleichen** | Tools nebeneinander gegenüberstellen | Premium |
+| **Watchlist** | Tools als Favoriten speichern | Premium |
+| **Analytics** | Statistiken, Top-Tools, Verteilungen | Alle |
+| **Admin** | Nutzerverwaltung, Audit-Log, Papierkorb | Admin |
+| **Trash** | Soft-gelöschte Tools wiederherstellen oder endgültig löschen | Admin |
+
+## Funktionen & Felder im Detail
+
+Die **Referenz** ist automatisch aus der OpenAPI-Spezifikation generiert und
+deckt damit garantiert *alle* Endpunkte und Datenfelder der aktuellen Version
+ab:
+
+- [Endpunkte](/docs/reference/endpoints/tools) — jede API-Operation mit
+  Parametern und Antwort-Schemas.
+- [Datenmodell & Felder](/docs/reference/schemas/tool) — jedes Feld mit Typ,
+  Pflichtstatus und Bedeutung.
+
+> Die Referenz ist **versionsgebunden**: Wähle oben rechts eine ältere Version,
+> um den API-Stand dieses Releases zu sehen.
+
+## Erste Schritte
+
+- Neu hier? Starte mit dem [Erste-Schritte-Guide](/docs/handbook/getting-started).
+- Möchtest du ein Tool eintragen? Siehe [Tool anlegen](/docs/handbook/tool-anlegen).
+- Formulare zeigen neben jedem Feld ein **Hilfe-Icon (?)**, das direkt zur
+  Erklärung des Felds in der Doku springt.
+
+## Wo ist der Quellcode?
+
+Über das **Repository-Logo oben rechts** gelangst du direkt zum Quellcode auf
+GitHub.
@@ -0,0 +1,49 @@
+---
+title: Tool anlegen & bearbeiten
+order: 3
+---
+
+# Tool anlegen & bearbeiten
+
+## Neues Tool anlegen
+
+Unter **Tool hinzufügen** legst du ein neues Tool an. Die Felder entsprechen
+dem Eingabeschema [`ToolInput`](/docs/reference/schemas/toolinput):
+
+| Feld | Pflicht | Bedeutung |
+| --- | --- | --- |
+| **Name** | ja | Anzeigename des Tools (min. 2 Zeichen). |
+| **Beschreibung** | ja | Was tut das Tool, warum nutzen es Leute? (min. 10 Zeichen) |
+| **Kategorie** | ja | Zugeordnete Kategorie (aus bestehenden Kategorien wählbar). |
+| **Website-URL** | nein | Offizielle Website (`https://…`). |
+| **Icon-/Logo-URL** | nein | Direktlink zu einem Logo-Bild. |
+| **Features** | nein | Schlüsselfähigkeiten, z. B. „Echtzeit-Kollaboration“. Bereits bekannte Features sind auswählbar. |
+| **Tags** | nein | Schlagwörter zum Auffinden. Bereits bekannte Tags sind auswählbar. |
+
+> Hinter jedem Label findest du ein **Hilfe-Icon (?)** — es verlinkt direkt
+> zur Feldbeschreibung in dieser Doku.
+
+### Hinweise
+
+- **Features & Tags** sind Listen. Über **+ Feature / + Tag** fügst du weitere
+  Einträge hinzu; über das ✕-Symbol entfernst du sie.
+- URLs müssen absolut und gültig sein.
+- Leere Einträge in Feature-/Tag-Listen werden beim Speichern verworfen.
+
+## Tool bearbeiten
+
+Auf der Detailseite eines Tools öffnet **Bearbeiten** das Formular mit den
+aktuellen Werten. Du kannst Name, Beschreibung, Kategorie, URLs, Features und
+Tags ändern. Nur angemeldete Nutzer:innen können Tools bearbeiten.
+
+## Tool löschen
+
+Über die Detailseite kannst du ein Tool **in den Papierkorb verschieben**
+(Soft-Delete). Es verschwindet aus dem Katalog, bleibt aber im Papierkorb
+erhalten. Siehe [Administration & Papierkorb](/docs/handbook/administration).
+
+## Zugehörige Endpunkte
+
+- [`POST /tools`](/docs/reference/endpoints/tools#createtool) — Tool anlegen
+- [`PATCH /tools/{id}`](/docs/reference/endpoints/tools#updatetool) — Tool bearbeiten
+- [`DELETE /tools/{id}`](/docs/reference/endpoints/tools#deletetool) — Tool löschen
@@ -0,0 +1,46 @@
+---
+title: Vergleichen & Watchlist
+order: 5
+---
+
+# Vergleichen & Watchlist
+
+Diese Funktionen sind für **Premium-Nutzer:innen** verfügbar.
+
+## Tools vergleichen
+
+Mit **Vergleichen** stellst du mehrere Tools nebeneinander und siehst deren
+Daten auf einen Blick — ideal für die Tool-Auswahl.
+
+1. Füge Tools über die **Vergleichsleiste** (Vergleichs-Icon auf Karten) hinzu.
+2. Öffne den Bereich **Vergleichen**. Die Tools erscheinen in der gewählten
+   Reihenfolge.
+3. Die Vergleichsansicht zeigt pro Tool die wichtigsten Felder und
+   Durchschnittswerte.
+
+Der zugrunde liegende Endpunkt ist
+[`GET /compare`](/docs/reference/endpoints/tools#listcomparetools) mit dem
+Parameter `ids` (kommagetrennt). Ohne Premium-Berechtigung liefert er `403`.
+
+## Watchlist
+
+Die **Watchlist** ist deine persönliche Favoritenliste:
+
+- **Hinzufügen/Entfernen:** Nutze das Lesezeichen-Symbol auf der
+  Tool-Karte oder der Detailseite.
+- Die gespeicherte Reihenfolge bleibt erhalten.
+- Sie wird über [`GET /auth/me/watchlist`](/docs/reference/endpoints/auth#getmewatchlist)
+  geladen; das Setzen erfolgt über
+  [`PUT /auth/me/preferences`](/docs/reference/endpoints/auth#updatemepreferences)
+  (Feld `watchlist`).
+
+### Feld `watchlist`
+
+Das Feld `watchlist` in [`UserPreferences`](/docs/reference/schemas/userpreferences)
+ist ein Array von Tool-IDs in gespeicherter Reihenfolge:
+
+| Feld | Typ | Bedeutung |
+| --- | --- | --- |
+| `view` | string | Ansichtsmodus (`grid`, `table`, `rows`). |
+| `density` | string | Dichte (`cozy`, `compact`). |
+| `watchlist` | integer[] | Tool-IDs in Favoriten-Reihenfolge. |
@@ -0,0 +1,35 @@
+# v0.7.0 — Release Notes
+
+**Datum:** 2026-08-03 · **Tag:** [`v0.7.0`](https://git.kubebase.de/admin/tool-evaluator/tags/v0.7.0)
+
+## Neue Features
+
+- Version-gebundene **Release-Dokumentation** in der App unter `/docs`
+  (Index + Detailseite je Version, Markdown aus `docs/releases/`).
+- Generiertes Release-Vorlage (`docs/releases/TEMPLATE.md`) und
+  Sync-Schritt für den Frontend-Build.
+
+## Fixes & Verbesserungen
+
+- `tsx` auf 4.23.4 angehoben — letzte veraltete Abhängigkeit im Workspace
+  (`pnpm outdated -r` ist jetzt leer).
+
+## API-Änderungen
+
+- Keine Breaking Changes an der API.
+
+## Betrieb / Upgrade
+
+- **Env-Vars:** unverändert.
+- **Migration:** keine.
+- **Breaking Changes:** keine.
+
+## Bekannte Einschränkungen
+
+- Die Doku ist bisher auf Release-Notes beschränkt; eine vollständige
+  API-/Feld-Referenz folgt in v0.8.0.
+
+## Links
+
+- Commit: [`520f917`](https://git.kubebase.de/admin/tool-evaluator/commit/520f917)
+- Tag: [`v0.7.0`](https://git.kubebase.de/admin/tool-evaluator/tags/v0.7.0)
@@ -0,0 +1,46 @@
+# v0.8.0 — Release Notes
+
+**Datum:** 2026-08-03 · **Tag:** [`v0.8.0`](https://git.kubebase.de/admin/tool-evaluator/tags/v0.8.0)
+
+## Neue Features
+
+- **Vollständige Dokumentations-Site** in mkdocs-Optik unter `/docs`:
+  - **Handbuch** mit verständlichen Erklärungen zu allen Features
+    (Erste Schritte, Tool anlegen, Bewertungen, Vergleichen, Watchlist,
+    Analytics, Administration, Datenmodell).
+  - **Automatisch generierte Referenz** aus `lib/api-spec/openapi.yaml`:
+    alle Endpunkte und Datenfelder (Typ, Pflichtstatus, Constraints) —
+    damit ist garantiert, dass *jedes* Feature dokumentiert ist.
+  - **Suche** über Handbuch, Endpunkte und Felder.
+  - **Versions-Dropdown**: ältere Releases behalten ihre vollständige
+    Feld-/Endpunkt-Referenz als Snapshot.
+  - **Repo-Link** oben rechts zur Quelle.
+- **Hilfe-Buttons (?) in Formularen** (NetBox-Stil): neben jedem Feld
+  springt ein Icon direkt zur Feldbeschreibung in der Doku.
+
+## Fixes & Verbesserungen
+
+- Doku-Generator `scripts/src/generate-docs.mjs` ersetzt den bisherigen
+  `sync-release-docs.mjs` (OpenAPI-Parsing, Handbuch, Suchindex, Snapshots).
+- Dokumentation für v0.7.0 nachgezogen.
+
+## API-Änderungen
+
+- Keine Breaking Changes an der API.
+
+## Betrieb / Upgrade
+
+- **Env-Vars:** unverändert.
+- **Migration:** keine.
+- **Breaking Changes:** keine.
+
+## Bekannte Einschränkungen
+
+- Handbuch & Referenz gelten für die aktuelle Version; ältere Versionen
+  zeigen ihre Release-Notes und einen Referenz-Snapshot, sofern beim Release
+  erzeugt (`node scripts/src/generate-docs.mjs --snapshot vX.Y.Z`).
+
+## Links
+
+- Commit: [`<short-sha>`](https://git.kubebase.de/admin/tool-evaluator/commit/<short-sha>)
+- Tag: [`v0.8.0`](https://git.kubebase.de/admin/tool-evaluator/tags/v0.8.0)