From 9c566492ab8261446dd26ed92f5f2a0b20dcb350 Mon Sep 17 00:00:00 2001
From: HomeOS Bootstrap <homeos@localhost>
Date: Sat, 18 Jul 2026 02:10:47 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E2=80=94=20Ring=20add-on=20se?=
 =?UTF-8?q?tup,=20PWA=20install,=20full=20services=20table?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document the opt-in ring-mqtt bridge flow (gen-passwd → --profile addons →
ring-mqtt web UI login → Add-ons install), the PWA install-to-home-screen, and
the previously-undocumented mqtt-listener / mosquitto / discovery / ring-mqtt
services with their ports.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md | 34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index c987e4b..4647b30 100644
--- a/README.md
+++ b/README.md
@@ -46,13 +46,45 @@ docker compose exec app php artisan test # test suite
 docker compose logs -f app               # logs
 ```
 
+## Add-ons
+
+On-demand integrations, managed under **Add-ons** in the sidebar.
+
+### Ring (cloud, opt-in)
+
+Ring has no local API, so HomeOS bridges it via [ring-mqtt](https://github.com/tsightler/ring-mqtt),
+which runs as an **opt-in** container (it never starts on a Ring-less setup):
+
+```bash
+bash docker/mosquitto/gen-passwd.sh              # seeds the least-privileged `ring` broker account
+docker compose --profile addons up -d ring-mqtt  # start the bridge
+```
+
+Then:
+
+1. Open **http://<host>:${RING_UI_PORT:-55123}** (ring-mqtt's own web UI) and sign in with your
+   Ring account (email + password + 2FA). It mints and stores the refresh token — HomeOS never
+   handles Ring's OAuth itself.
+2. In HomeOS → **Add-ons → Ring → Install**, then **Connect account**.
+3. Ring devices (doorbell, cameras, sensors) appear automatically under **Devices**, tagged **Cloud**.
+
+## Install as an app (PWA)
+
+HomeOS ships a web manifest + service worker, so it installs to a tablet/phone home screen
+("Add to Home Screen") and runs full-screen. Use the **Steuerung** (`/panel`) tab as the tablet
+control surface. Install requires HTTPS in production (localhost is exempt for testing).
+
 ## Services & ports
 
 | Service | Role | Host port |
 |---|---|---|
 | `app` | php-fpm + nginx + supervisor | `${APP_PORT:-80}` |
 | `reverb` | websockets (proxied same-origin via nginx `/app`) | `${REVERB_HOST_PORT:-6001}` |
-| `horizon` · `scheduler` | queue workers · cron | — |
+| `horizon` · `scheduler` | queue workers · cron (presence, metrics, automations) | — |
+| `mqtt-listener` | subscribes the bus, dispatches ingest jobs | — |
+| `mosquitto` | MQTT broker (auth + per-client ACLs) | `${MQTT_HOST_PORT:-1883}` |
+| `discovery` | mDNS/SSDP sidecar (host network) | — |
+| `ring-mqtt` | Ring bridge — **opt-in** (`--profile addons`) | `${RING_UI_PORT:-55123}` |
 | `db` | PostgreSQL 17 + TimescaleDB | `127.0.0.1:${DB_HOST_PORT:-5432}` |
 | `redis` | cache / queue | — |