feat(agent): harden API-first service

pv-agent/agent/README.md

@@ -43,9 +43,14 @@ python -m agent.cli eval
 python -m agent.cli eval --answers --json-out data/eval-report.json
 
 # 4) HTTP-API + Test-Chat
-python -m agent.cli serve             # http://127.0.0.1:8080 (/ask, /health, /reindex)
+python -m agent.cli serve             # http://127.0.0.1:8080 (/v1/ask, /v1/health, /v1/reindex)
 ```
 
+Der stabile v1-Vertrag, Bearer-Authentisierung, Fehlersemantik und die
+Datenschutzgrenze für die spätere Odoo-Anbindung sind in `docs/API.md`
+dokumentiert. v1 ist zustandslos und akzeptiert keine Mandanten-, Mitarbeiter-
+oder Abrechnungsobjekte.
+
 ## Konfiguration (Umgebungsvariablen)
 
 | Variable | Default | Bedeutung |
@@ -69,6 +74,8 @@ python -m agent.cli serve             # http://127.0.0.1:8080 (/ask, /health, /r
 | `PV_MAX_CONTEXT_CHARS` | `90000` | User-Content-Budget; niedrig gerankte Blöcke werden ganz weggelassen (`trim_results`) |
 | `PV_CONTEXT_BLOCKS` | `8` | Kontextblöcke im Prompt |
 | `PV_PORT` | `8080` | API-Port |
+| `PV_API_KEY` | leer | Bearer-Key für `/v1/ask`; leer nur für lokale Entwicklung ohne Auth |
+| `PV_ADMIN_API_KEY` | leer | separater Bearer-Key für `/v1/reindex`; leer = `PV_API_KEY` verwenden |
 
 ## Deployment auf dem Host (Ollama-Maschine)
 
@@ -206,7 +213,7 @@ agent/
   retrieve.py       Hybrid-Retrieval (BM25 + Dense, RRF, cross_refs)
   ollama_client.py  Ollama-HTTP (embed + chat, think-Fallback)
   generate.py       Systemprompt, Post-Validierung, Verweigerung
-  api.py            FastAPI (/ask, /health, /reindex)
+  api.py            FastAPI v1 (/v1/ask, /v1/health, /v1/reindex), Auth + Request-IDs
   cli.py            ingest | ask | eval | serve
   eval/             goldset.yaml + evaluate.py
 web/index.html      Minimaler Test-Chat