feat(api): Codex: add /health endpoint with podman + systemd checks

AGENTS.md

@@ -0,0 +1,173 @@
+# AGENTS.md — podman-mvp (WebUI + API)
+
+## Goal
+Primary goal: extend functionality and evolve the platform.
+
+Feature development is the default workflow.
+
+Refactoring is allowed when:
+- it improves maintainability, OR
+- it is required to implement a feature.
+
+Refactoring must always:
+- be proposed first,
+- remain backward compatible,
+- not change existing behaviour or API contracts without agreement.
+
+---
+
+## Repository structure
+
+Backend (FastAPI)
+- control/app.py (main API)
+- control/app_images.py
+
+WebUI (static Apache)
+- webui/html/index.html
+- webui/html/assets/js/tabs/
+- webui/conf/httpd.conf
+
+---
+
+## Runtime architecture (IMPORTANT)
+
+Application runs inside a Podman pod.
+
+Pod created with:
+
+podman pod create \
+  --name mvp-pod \
+  -p 8080:8000 \
+  -p 8081:8081 \
+  --userns=keep-id
+
+
+### Backend container
+
+Runs FastAPI control API with Podman access.
+
+Created with:
+
+podman run -d --pod mvp-pod \
+  --name mvp-backend \
+  --ipc=host \
+  --pid=host \
+  -e XDG_RUNTIME_DIR=/run/user/1000 \
+  -e DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus \
+  -v /run/user/1000:/run/user/1000:rw \
+  -v /run/user/1000/podman/podman.sock:/run/user/1000/podman/podman.sock:rw \
+  -v /home/kodi/.config/containers:/app/workloads:rw \
+  mvp-control:latest
+
+
+Important notes:
+- Backend communicates with Podman through unix socket.
+- User-session Podman is used (not root).
+- DBus access is required.
+- Host PID/IPC namespaces are intentional.
+
+Do NOT change these assumptions without proposal.
+
+---
+
+### WebUI container
+
+Static Apache frontend.
+
+podman run -d --pod mvp-pod \
+  --name mvp-webui \
+  -v $HOME/.config/podman-mvp/webui/html:/usr/local/apache2/htdocs:ro \
+  -v $HOME/.config/podman-mvp/webui/conf/httpd.conf:/usr/local/apache2/conf/httpd.conf:ro \
+  docker.io/library/httpd:2.4
+
+Frontend is static JS calling API through proxy.
+
+---
+
+## Access
+
+WebUI:
+http://127.0.0.1:8081/
+
+API (via proxy):
+http://127.0.0.1:8081/api/
+
+---
+
+## Testing workflow (REQUIRED)
+
+Always validate changes using curl.
+
+Example:
+
+curl -s http://127.0.0.1:8081/api/...
+
+Before proposing implementation:
+1. Analyse existing endpoints.
+2. Confirm available data using curl tests.
+3. Propose minimal change.
+4. Provide verification curl commands.
+
+---
+
+## Contract rules (HARD)
+
+- Never break existing API responses.
+- Never rename or remove JSON keys.
+- Maintain backward compatibility.
+
+New functionality must be added via:
+- new endpoints, OR
+- optional response fields.
+
+Security rules:
+- No shell=True
+- subprocess must be explicit and safe
+- Respect allowed_units.txt
+- Never assume systemd states.
+
+---
+
+## Change policy
+
+Preferred workflow:
+
+1. Analyse existing behaviour.
+2. Propose small implementation plan.
+3. Identify affected files.
+4. Provide curl validation tests.
+5. Implement after agreement.
+
+Avoid:
+- large rewrites
+- structural changes without need
+- hidden refactors.
+All significant changes must follow PR_RULES.md workflow.
+---
+
+## UI direction
+
+Target style:
+Portainer-like dashboard UI.
+
+Guidelines:
+- tables and overview panels
+- container status badges
+- row-level actions
+- minimalistic professional layout
+
+Do NOT introduce large frontend frameworks without agreement.
+
+---
+
+## Coding style
+
+Follow existing structure and conventions of each file.
+
+Do not reformat unrelated code.
+
+Minimize diff size whenever possible.
+
+## Safety boundaries
+
+Follow SAFE_FILES.md before modifying infrastructure or core files.