# 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.