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

docs/README.md

@@ -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`.