diff --git a/README.md b/README.md
index 6cf2fdd..5beb0fa 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,109 @@
-# alarm_app
+# alarm_widg
+
+Minimal alarm scheduler, part of CandyWidgets.
+
+Reads alarms from a TOML configuration file and triggers them at the configured times.
+
+> **Work in progress:** The project is still under active development and may change.
+
+## Install
+
+Build the release binary:
+
+```bash
+cargo build --release
+````
+
+Install it somewhere in your `$PATH`, for example:
+
+```bash
+install -Dm755 target/release/alarm_widg ~/.local/bin/alarm_widg
+```
+
+Install the systemd user service:
+
+```bash
+mkdir -p ~/.config/systemd/user
+cp extra/alarm-widg.service ~/.config/systemd/user/
+systemctl --user daemon-reload
+systemctl --user enable --now alarm-widg.service
+```
+
+Check the service:
+
+```bash
+systemctl --user status alarm-widg.service
+```
+
+## Configure
+
+Create or edit:
+
+```text
+~/.config/candywidgets/alarm-app/config.toml
+```
+
+Example:
+
+```toml
+# Daily task
+[[alarm]]
+title = "Take medication"
+time = "08:00"
+days = [1, 2, 3, 4, 5, 6, 0]
+
+# Daily task, disabled
+[[alarm]]
+title = "Check personal email"
+time = "18:00"
+days = [1, 2, 3, 4, 5, 6, 0]
+enabled = false
+
+# Weekly task
+[[alarm]]
+title = "Water plants"
+time = "10:00"
+days = [0]
+
+# A few days each week
+[[alarm]]
+title = "Exercise"
+time = "17:30"
+days = [1, 3, 5]
+
+# Specific date
+[[alarm]]
+title = "Submit monthly report"
+time = "16:00"
+dates = ["2026-08-31"]
+
+# Multiple specific dates
+[[alarm]]
+title = "Project deadlines"
+time = "17:00"
+dates = [
+    "2026-08-15",
+    "2026-08-22",
+    "2026-08-29",
+]
+color = "FFFFCC00"
+```
+
+### Options
+
+| Option    | Description                                         |
+| --------- | --------------------------------------------------- |
+| `title`   | Alarm title                                         |
+| `time`    | Time in `HH:MM` format                              |
+| `days`    | Recurring days, `0` = Sunday through `6` = Saturday |
+| `dates`   | Specific dates in `YYYY-MM-DD` format               |
+| `color`   | Optional ARGB hexadecimal color                     |
+| `enabled` | Enable or disable the alarm, defaults to `true`     |
+
+Each alarm must specify either `days` or `dates`.
+
+## License
+
+GPL-3.0-or-later. See `LICENSE`.
+
 
-Minimal alarm app
\ No newline at end of file