# Dokumentations- & Archiv-Subsystem (2026-08-03, validiert)

Nutzer-Präferenz abs. Priorität: **ALLES wird automatisch dokumentiert und
jederzeit sichtbar** („Das will ich immer sehen können"). Doku ist kein
nachgelagerter Text, sondern ein live generiertes Panel + chronologisches Archiv.

## Komponenten

| Komponente | Ort | Funktion |
|------------|-----|----------|
| Ereignis-Log | `/srv/work/log/events.jsonl` | Jede Aktion, JSONL append |
| Live-Panel | `Dokumentationen.perfekt-ohne-en.de` | Echtzeit-Übersicht (Tasks, Agenten, Kosten, Log) |
| Tages-Archiv | `Archiv.perfekt-ohne-en.de` | Pro-Tag-Zusammenfassung, chronologisch |

## Skripte

- `/usr/local/bin/mesh-log.sh <aktion> <detail> [agent] [kosten_eur]` —
  appendet Zeile an `events.jsonl`. Immer bei jeder Aktion aufrufen!
  ```json
  {"ts":"<ISO>","aktion":"...","agent":"agent-a","kosten_eur":0.000,"detail":"..."}
  ```
- `/usr/local/bin/duo-master-report.sh` — regeneriert das Live-Panel aus
  `/srv/work/tasks` **und** `/srv/work/log/events.jsonl` (letzte 40 Events,
  heutige Kosten = summiert aus events.jsonl). Cron: `* * * * * sleep 30`.
- `/usr/local/bin/duo-daily-archive.sh` — erzeugt `Archiv.perfekt-ohne-en.de/<datum>.html`
  mit Tages-Stats (Aktionen, Kosten, fertig/offen/bugfix) + Ereignisliste.
  Schreibt außerdem `index.html` als chronologische Linkliste.
  Cron: `50 23 * * *` (täglich 23:50).

## Pitfalls (real getestet)

- **`ls /path/*.json` unter `set -euo pipefail` bricht mit Exit 2 ab**, wenn der
  Glob leer ist (kein Match). Fix: `shopt -s nullglob` vor den Zähl-Loops
  einsetzen (gilt für `duo-master-report.sh` UND `duo-daily-archive.sh`).
- **Website-Verifikation:** `curl -s -o /dev/null -w "%{http_code}" <url>` nach
  jeder Generierung. Standard-Docroot existiert, aber der generierte Inhalt
  fehlt erst → `403/404` = Skript brach ab, nicht die Website.
- **Grid/Liste leeres Verzeichnis:** `grep -v index.html` auf leeren Glob
  ebenfalls mit `nullglob` schützen, sonst Exit 2.

## Einrichtung (Subdomain)

```bash
mkdir -p /var/www/Archiv.perfekt-ohne-en.de
# nginx vhost (listen 80 → root), ln -sf ins sites-enabled, nginx -t && reload
certbot --nginx -d Archiv.perfekt-ohne-en.de --redirect --agree-tos -m admin@perfekt-ohne-en.de
```
Big-Real-Fix: Die Subdomain erreicht per DNS denselben Server (92.60.38.175),
eigenes cert + eigener vhost pro Site.

## Budget

Kosten werden pro Ereignis in `events.jsonl` geloggt und pro Tag summiert
(Live-Panel zeigt „Heutige Kosten"). Budget-Regel: 1 €/Agent/Tag, kein
sprunghafter Modellwechsel ohne expliziten Nutzerwunsch.