Added README

README.md

@@ -0,0 +1,72 @@
+# imap-idle-caldav
+
+A Python daemon that monitors an IMAP mailbox via IDLE for iMIP emails (event invitations, RSVP replies, cancellations) and ICS attachments, then updates a CalDAV calendar accordingly.
+
+## Features
+
+- **IMAP IDLE** — real-time monitoring with automatic reconnection and exponential backoff
+- **iMIP support** — handles REQUEST (create/update), REPLY (attendee RSVP), and CANCEL methods
+- **ICS attachments** — picks up `.ics` files and `application/ics` MIME parts
+- **CalDAV sync** — creates, updates, and cancels events on any CalDAV server (Nextcloud, Radicale, etc.)
+- **Graceful shutdown** — handles SIGTERM/SIGINT cleanly
+
+## Installation
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Configuration
+
+Copy the example config and fill in your credentials:
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+```yaml
+imap:
+  host: imap.example.com
+  port: 993
+  username: user@example.com
+  password: secret
+  folder: INBOX
+  ssl: true
+
+caldav:
+  url: https://caldav.example.com/dav/calendars/user/calendar/
+  username: user@example.com
+  password: secret
+
+logging:
+  level: INFO   # DEBUG, INFO, WARNING, ERROR
+```
+
+## Usage
+
+```bash
+# Using the entry point
+imap-idle-caldav -c config.yaml
+
+# Or as a module
+python -m imap_idle_caldav -c config.yaml
+```
+
+The daemon will connect to IMAP, enter IDLE mode, and process incoming calendar emails as they arrive. It re-idles every 5 minutes per RFC 2177 and automatically reconnects on disconnection.
+
+## Project Structure
+
+```
+imap_idle_caldav/
+├── __main__.py          # Entry point, signal handling
+├── config.py            # YAML config loading & validation
+├── imap_client.py       # IMAP connection & IDLE loop
+├── email_processor.py   # ICS extraction from emails
+└── caldav_client.py     # CalDAV create/update/cancel operations
+```
+
+## License
+
+MIT