From dc6339b6de7e1a40497b851988c3d6b57aa2fabd Mon Sep 17 00:00:00 2001
From: sam ditmeijer <sam@mief.info>
Date: Tue, 9 Jun 2026 17:44:14 +0000
Subject: [PATCH] docs: README for the v0.8.19 release

---
 README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..53b8977
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+# ViaVox
+
+Sync Microsoft 365 calendar (and soon contacts) into Nextcloud.
+
+ViaVox is the Nextcloud companion app for the **ViaVox Syncer** service: a
+webhook-based Microsoft Graph → Nextcloud CalDAV bridge that keeps Outlook /
+Exchange Online calendars in sync with each Nextcloud user's personal
+calendar, both directions, in near-real-time.
+
+This repo distributes the **Nextcloud app** half of the stack. The companion
+syncer service is deployed separately (admins configure its URL + shared
+token).
+
+## What it does
+
+- Each Nextcloud user can connect / disconnect their own Microsoft 365
+  account from **Settings → Personal → ViaVox**.
+- Once connected, Outlook events flow into the user's personal calendar via
+  webhook notifications (no polling), and edits made in Nextcloud Calendar
+  flow back to Outlook.
+- Recurring meetings — including exceptions, cancellations, DST transitions,
+  attendees and RSVPs — are handled end-to-end.
+- An admin overview shows per-user connection status and sync health.
+
+## Install
+
+1. **Download** the latest `viavox-X.Y.Z.tgz` release asset (see the
+   **Releases** page).
+2. Extract into your Nextcloud installation's `apps/` directory so that
+   `apps/viavox/appinfo/info.xml` exists:
+
+   ```bash
+   tar xzf viavox-0.8.19.tgz -C /var/www/nextcloud/apps/
+   chown -R www-data:www-data /var/www/nextcloud/apps/viavox
+   ```
+
+3. Enable the app:
+
+   ```bash
+   occ app:enable viavox
+   ```
+
+4. As an admin, open **Settings → Administration → ViaVox**, enter the
+   ViaVox Syncer base URL and shared NC-app token, hit *Save* and then
+   *Test connection*.
+5. Each user can now open **Settings → Personal → ViaVox** and click
+   *Connect Microsoft 365* to start syncing.
+
+## Requirements
+
+- Nextcloud 30 or newer.
+- PHP 8.1+.
+- A reachable ViaVox Syncer instance (separately deployed).
+- A Microsoft 365 tenant with an App Registration that has
+  `Calendars.ReadWrite` delegated permission.
+
+## License
+
+AGPL-3.0-or-later. See `COPYING` inside the package.
+
+## Support
+
+For installation help or to report issues, contact the maintainer (see
+`appinfo/info.xml` for the e-mail address).