docs: add Agent API docs, OpenAPI field descriptions, and project context files

server/api/agent.py

@@ -23,6 +23,7 @@ NO_STORE = {"Cache-Control": "no-store"}
 
 @router.get("/health")
 async def agent_health(_: dict = Depends(require_agent)) -> JSONResponse:
+    """Liveness-Check der App."""
     db = await get_db()
     try:
         db_version = await current_version(db)
@@ -36,6 +37,7 @@ async def agent_health(_: dict = Depends(require_agent)) -> JSONResponse:
 
 @router.get("/status")
 async def agent_status(_: dict = Depends(require_agent)) -> JSONResponse:
+    """Heutige Slot-Daten plus aktuelle Stats."""
     config = load_meds_config()
     db = await get_db()
     try:
@@ -47,7 +49,10 @@ async def agent_status(_: dict = Depends(require_agent)) -> JSONResponse:
 
 
 @router.post("/log")
-async def agent_log(payload: AgentLogEntry, _: dict = Depends(require_agent)) -> JSONResponse:
+async def agent_log(
+    payload: AgentLogEntry, _: dict = Depends(require_agent)
+) -> JSONResponse:
+    """Eine Einnahme für einen Slot loggen."""
     config = load_meds_config()
     if payload.slot_id not in {s.id for s in config.slots}:
         raise HTTPException(status_code=400, detail="Unknown slot")
@@ -58,23 +63,35 @@ async def agent_log(payload: AgentLogEntry, _: dict = Depends(require_agent)) ->
 
     db = await get_db()
     try:
-        await db.execute("DELETE FROM intake_log WHERE slot_id = ? AND day = ?", (payload.slot_id, day))
+        await db.execute(
+            "DELETE FROM intake_log WHERE slot_id = ? AND day = ?",
+            (payload.slot_id, day),
+        )
         await db.execute(
             "INSERT INTO intake_log (id, slot_id, day, status, logged_at, source) VALUES (?, ?, ?, ?, ?, ?)",
             (new_id(), payload.slot_id, day, status, logged_at, payload.source),
         )
         if status == "taken":
-            await db.execute("DELETE FROM snooze WHERE slot_id = ? AND day = ?", (payload.slot_id, day))
+            await db.execute(
+                "DELETE FROM snooze WHERE slot_id = ? AND day = ?",
+                (payload.slot_id, day),
+            )
         await db.commit()
     finally:
         await db.close()
 
     logger.info("Agent logged slot=%s status=%s day=%s", payload.slot_id, status, day)
-    return JSONResponse({"ok": True, "slot_id": payload.slot_id, "day": day, "status": status}, headers=NO_STORE)
+    return JSONResponse(
+        {"ok": True, "slot_id": payload.slot_id, "day": day, "status": status},
+        headers=NO_STORE,
+    )
 
 
 @router.get("/history")
-async def agent_history(days: int = 90, _: dict = Depends(require_agent)) -> JSONResponse:
+async def agent_history(
+    days: int = 90, _: dict = Depends(require_agent)
+) -> JSONResponse:
+    """Einnahme-Historie der letzten N Tage (max. 365)."""
     db = await get_db()
     try:
         data = await build_history(db, days=min(days, 365))
@@ -85,6 +102,7 @@ async def agent_history(days: int = 90, _: dict = Depends(require_agent)) -> JSO
 
 @router.get("/config")
 async def agent_config(_: dict = Depends(require_agent)) -> JSONResponse:
+    """Aktive Medikamenten-Konfiguration (Zeitzone, Slots)."""
     config = load_meds_config()
     return JSONResponse(
         {
@@ -97,7 +115,10 @@ async def agent_config(_: dict = Depends(require_agent)) -> JSONResponse:
 
 
 @router.post("/notify")
-async def agent_notify(payload: AgentNotifyRequest, _: dict = Depends(require_agent)) -> JSONResponse:
+async def agent_notify(
+    payload: AgentNotifyRequest, _: dict = Depends(require_agent)
+) -> JSONResponse:
+    """Push-Benachrichtigung an alle aktiven Subscriptions senden."""
     db = await get_db()
     try:
         sent = await send_push(