# AGENTS.md

Detta dokument styr hur agenter och utvecklare arbetar i detta repo.
Fokus: korrekthet, låg risk och underhållbarhet.

## 1) Syfte och prioritet

- Gäller hela repot.
- Kompletterar globala agentinstruktioner.
- Vid konflikt gäller striktare regel.

## 2) Repo-invarianter

- Appfiler ligger under `Apps/<app-id>/`.
- Varje app ska minst ha:
  - `docker-compose.yaml`
  - `README.md` (syfte, portar, volymer, privilegier, risker)
- Compose ska ha giltig top-level `name` (gemener + bindestreck).
- Endast `.yaml` används i repot (aldrig `.yml`).

## 3) Säkerhetsbaseline (Compose)

MUST:
- Pinna images till explicit version eller digest.
- Inte använda `:latest`.
- Hålla volymer snäva (`/DATA/AppData/$AppID/...`).

SHOULD:
- `security_opt: ["no-new-privileges:true"]`
- `cap_drop: ["ALL"]` när appen tillåter det.

Högrisk-inställningar är tillåtna men kräver varning och motivering:
- `privileged: true`
- `network_mode: host`
- mount av Docker-socket (`/var/run/docker.sock`)

Om någon högrisk-inställning används måste appens `README.md` innehålla:
- varför det behövs,
- vilka alternativ som utvärderats,
- vilka risker det innebär.

## 4) Arbetsflöde för ändringar

- Små, reviewbara ändringar först.
- Beskriv säkerhetspåverkan i PR.
- Lokal validering är rekommenderad under utveckling:

```bash
./scripts/validate-appstore.sh
```

- Lokal validering är inte blockerande för varje enskild commit.

## 5) Obligatorisk release-checklista

Inför release/publicering måste följande vara uppfyllt:

1. `./scripts/validate-appstore.sh` körd med `Validation OK`.
2. Ingen app använder `image: ...:latest`.
3. `x-casaos` metadata är satt och konsekvent.
4. Appens `README.md` är uppdaterad.
5. Eventuella högrisk-inställningar är tydligt motiverade.

## 6) Review-krav

PR som ändrar appar ska explicit ange:
- vilka app-id:n som påverkas,
- säkerhetsrisk (låg/medel/hög),
- om högrisk-inställningar introduceras eller ändras.

## 7) Testkrav för containerappar

För nya appar eller större ändringar i befintliga appar (routing, discovery, auth, nätverk, secrets, cert-hantering) ska integrationstester ingå.

Minimikrav:

- Testa med mockade externa gränser (t.ex. Docker API, reverse proxy API, DNS/API-provider), så testerna är reproducerbara lokalt.
- Verifiera minst ett fail-closed-scenario (saknad/ogiltig secret, API-fel, otillåten metadata) där appen inte exponerar tjänster oavsiktligt.
- Verifiera att endast explicit tillåtna containrar/endpoints exponeras.

Tester ska dokumenteras i appens `README.md` med exakt körkommando.

## 8) Branch-namnstandard

När en ny branch skapas ska formatet vara:

`<appnamn>/<initial|bugfix|update>/<detalj>`

Regler för `<detalj>`:

- `initial`: max 5 ord som beskriver vad som byggs.
- `bugfix`: vad som fixas (kort och konkret).
- `update`: versionsuppdatering i formen `vX.Y.Z-to-vA.B.C`.