Add caddy-autogen verification guide and readiness policy

AGENTS.md

@@ -91,3 +91,30 @@ 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`.
+
+## 9) Parallellt agentarbete och git-scope
+
+- När en ny app skapas ska en ny mapp alltid skapas under `Apps/<app-id>/`.
+- Flera agenter kan arbeta samtidigt. Fråga alltid innan du skapar ny branch eller byter branch, för att undvika krockar.
+- `git add` och `git commit` får endast omfatta filer i den egna appens undermapp under `Apps/<app-id>/`.
+
+## 10) Verifieringsdokument när app är redo
+
+När en app bedöms som \"redo\" ska appmappen innehålla en verifieringsfil:
+
+- `Apps/<app-id>/HOW_TO_VERIFY.md`
+
+Filen ska vara praktiskt körbar och innehålla:
+
+- tydliga förutsättningar (miljö, DNS, secrets, beroenden),
+- positiva testfall med förväntade resultat,
+- minst ett fail-closed/negativt testfall,
+- exakta kommandon för att verifiera DNS, nät och TLS,
+- en sektion \"data att samla\" för snabb Codex-felsökning.
+
+Sektionen \"data att samla\" ska minst täcka:
+
+- versions-/buildinfo (appversion, branch/commit eller zip + checksum),
+- relevant konfiguration (med maskade secrets),
+- loggar från berörda containers,
+- konkreta felobservationer (hostname, tidpunkt, förväntat vs faktiskt beteende).

Apps/caddy-autogen/HOW_TO_VERIFY.md

@@ -0,0 +1,121 @@
+# HOW_TO_VERIFY (Caddy AutoGen)
+
+Denna fil beskriver hur du verifierar appen i en riktig ZimaOS-miljö och vilken data som behövs vid felsökning.
+
+## 1) Förutsättningar
+
+- ZimaOS med appen `caddy-autogen` installerad.
+- En fungerande domän i Cloudflare (publik zon).
+- AdGuard Home (eller annan lokal DNS) i LAN.
+- Cloudflare API-token med minst:
+  - `Zone.Zone:Read`
+  - `Zone.DNS:Edit`
+- Minst en målcontainer med web UI-port.
+
+## 2) Grundkonfiguration
+
+Sätt appvariabler i `caddy-autogen`:
+
+- `BASE_DOMAIN=home.example.com`
+- `WILDCARD_DOMAIN=home.example.com`
+- `CLOUDFLARE_API_TOKEN=<token>`
+- `REQUIRE_CLOUDFLARE=true`
+- `ALLOW_INTERNAL_TLS_FALLBACK=false`
+
+Konfigurera lokal DNS (AdGuard Home):
+
+- `A`/rewrite för `*.home.example.com` -> ZimaOS LAN-IP
+- `A`/rewrite för `home.example.com` -> ZimaOS LAN-IP
+
+## 3) Positivt test: endpoint skapas korrekt
+
+Exempel med Frigate (web UI på 5000):
+
+Sätt env-vars på Frigate-containern:
+
+```text
+LABEL_CADDY_ENABLE=true
+LABEL_CADDY_TARGET_PORT=5000
+LABEL_CADDY_HOST=frigate
+LABEL_CADDY_SCHEME=http
+LABEL_CADDY_PATH=/
+```
+
+Verifiera:
+
+1. Vänta 15-30 sekunder (default polling).
+2. Öppna `https://frigate.home.example.com`.
+3. Kontrollera att sidan svarar med giltigt certifikat.
+4. Kontrollera att media-portar (8554/8555) inte blivit egna hostnamn/endpoints.
+
+Förväntat resultat:
+
+- Endpoint finns för web UI.
+- Certifikat utfärdas via Let's Encrypt DNS-01.
+- Endast explicit målport routas.
+
+## 4) Negativt test: fail-closed
+
+Scenario A, ingen opt-in:
+
+1. Ta bort `LABEL_CADDY_ENABLE=true` från målcontainern.
+2. Vänta en polling-cykel.
+3. Kontrollera att endpointen försvinner/slutar routas.
+
+Scenario B, saknad Cloudflare-token:
+
+1. Sätt `REQUIRE_CLOUDFLARE=true`.
+2. Ta bort eller ogiltiggör `CLOUDFLARE_API_TOKEN`.
+3. Verifiera att ingen ny extern route publiceras.
+
+Förväntat resultat:
+
+- Appen exponerar inte tjänster oavsiktligt.
+- Loggar visar tydligt fel kring token/Cloudflare.
+
+## 5) Kommandon för snabb verifiering
+
+Byt `<domain>` och `<host>` enligt din miljö.
+
+```bash
+nslookup frigate.home.example.com
+curl -vk https://frigate.home.example.com/
+openssl s_client -connect frigate.home.example.com:443 -servername frigate.home.example.com </dev/null
+```
+
+Containerloggar:
+
+```bash
+docker logs --tail 200 caddy-autogen-discovery
+docker logs --tail 200 caddy-autogen
+docker logs --tail 200 caddy-autogen-socket-proxy
+```
+
+## 6) Data att samla innan du ber en Codex-agent om hjälp
+
+Samla detta först. Det kortar felsökningstiden avsevärt.
+
+1. Miljöinfo:
+- ZimaOS-version.
+- Appens branch/commit eller zip-artefakt (filnamn + SHA256).
+- Vilken DNS-server som används lokalt.
+
+2. Appkonfiguration:
+- Alla app-env-vars för `caddy-autogen` (maska secrets).
+- Målcontainerns `LABEL_CADDY_*`-env-vars.
+- Målcontainerns publicerade portar.
+
+3. Nät/TLS-bevis:
+- `nslookup`-svar från en LAN-klient.
+- `curl -vk` output mot endpoint.
+- `openssl s_client` sammanfattning av cert/issuer.
+
+4. Loggar:
+- Senaste 200 rader från `caddy-autogen-discovery`.
+- Senaste 200 rader från `caddy-autogen`.
+- Senaste 200 rader från `caddy-autogen-socket-proxy`.
+
+5. Problemdefinition:
+- Exakt hostname som inte fungerar.
+- Förväntat beteende och faktiskt beteende.
+- Tidpunkt när felet observerades.

Apps/caddy-autogen/README.md

@@ -102,3 +102,5 @@ Testerna mockar Docker API-svar och Caddy `/load`-anrop och verifierar:
 - opt-in-regler (endast markerade containers exponeras),
 - säker portselektionslogik (inga media/UDP-portar routas av misstag),
 - fail-closed beteende när Cloudflare-token saknas.
+
+För verifiering i riktig ZimaOS-miljö, se `HOW_TO_VERIFY.md` i samma mapp.