docs: expand README with repo overview and deployment method

Part-of: <http://gitlab.vnc.biz/uxf/vnctalk-prosody/-/merge_requests/3>

README.md

@@ -1,5 +1,55 @@
-# Vnctalk Prosody
+# VNCtalk Prosody
 
-dockerized build for vnctalk prosody
+Dockerized **Prosody 13.0.6** XMPP server for VNCtalk, built from source against
+Lua 5.4 on Alpine. The Dockerfile compiles Prosody, applies source patches, and
+layers on custom Lua modules — producing a single image deployed to Kubernetes
+via the bundled Helm chart and ArgoCD.
 
-this repository contains all patches and custom modules to run prosody for vnctalk
+## Repository layout
+
+| Path | Purpose |
+|------|---------|
+| `Dockerfile` | Multi-stage build: builder applies `patches/*.patch` to the extracted Prosody source, then `./configure --idn-library=idn --lua-version=5.4 && make install`. Final stage copies the built tree + `vnctalk/` modules + `config/`. |
+| `patches/` | Unified diffs against upstream Prosody core files, applied with `patch -p1 --fuzz=0` before configure. Adding/removing a `.patch` needs no Dockerfile change (glob-based). See `patches/README.md` for per-patch intent. |
+| `vnctalk/` | VNCtalk-specific Prosody modules (`mod_vnc_*`, `mod_http_rest`, `mod_alias`, `mod_webpresence`, …), copied wholesale to `/usr/local/lib/prosody/modules/`. |
+| `config/` | Runtime config template (`prosody.cfg.lua.template`), `startup.sh` (renders config via `envsubst`, writes certs, launches Prosody), `healthcheck.sh`, and `startup-sidecar.sh` (static-file/redirect sidecar). |
+| `helm/prosody/` | Helm chart for Kubernetes deployment (`Chart.yaml`, `values.yaml`, `templates/`). |
+| `argo/prosody.yaml` | ArgoCD `Application` manifest — the canonical deploy config (image tag, ingress, env vars). |
+| `db-customization/` | PostgreSQL schema/migration SQL for the Prosody 13 database (applied out-of-band, not by the container). |
+| `tests/` | pytest + slixmpp integration suite (~86 tests) with aiohttp mocks and a compose test harness. |
+
+## Deployment
+
+The **only intended deployment method** is the Helm chart in `helm/prosody/`,
+synced to the cluster by **ArgoCD** via `argo/prosody.yaml`.
+
+```
+argo/prosody.yaml  →  helm/prosody/  →  Docker image (release-13.0.6-vnc)
+```
+
+- **ArgoCD** (`argo/prosody.yaml`) is the source of truth for the live image tag,
+  ingress annotations, TLS, and environment variables. It references the Helm
+  chart and overrides values as needed.
+- **Helm chart** (`helm/prosody/`) defines the Deployment, Service, Ingress,
+  HPA, PDB, and ServiceAccount templates.
+- **Docker image** is built by GitLab CI from the `Dockerfile`, pushed to
+  `eu.gcr.io`, and referenced by tag in `argo/prosody.yaml`.
+
+No other deployment method is supported. The `test.sh` / `docker-compose.yml`
+files are for local testing only.
+
+## Build & test
+
+```sh
+# Build the image
+docker build -t vnctalk-prosody .
+
+# Run the compose test harness (postgres + mocks + prosody)
+make up
+source tests/venv/bin/activate
+pip install -r tests/requirements.txt
+pytest tests/ -v -c tests/pytest.ini
+make down
+```
+
+For full details see `AGENTS.md` and `tests/README.md`.