# Dokumentation (Handbuch, API-Referenz, Release-Notes)

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` — Notes pro Release
- `docs/releases/vX.Y.Z/reference.json` — API-Snapshot der jeweiligen Version

## Generator

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

- `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 ableiten:
   ```sh
   git log --oneline vX.Y.Z-1..vX.Y.Z
   ```
   (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: 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`.