chore: add a README

README.md

@@ -1,2 +1,45 @@
 # stolat
+Hackable script which can run your code when someone is getting closer to their birthday.
 
+## What can it do?
+Anything that you're willing to implement yourself.  After preconditions for sending a notification are met, the script will try to execute configured script inside the `scripts` directory.
+This means, that if you have an existing script/workflow for notifying users, say, through XMPP messages, SMS, e-mail, IRC, and so on, you can easily import it and run it.
+
+## Why bother using it?
+If your workflow is a little bit unorthodox, but you already have a working setup, then *stolat* with the help of cron checks the brithdays for you.
+This is exceptionally useful if you manage a multi-user service/server.  You don't need to worry about checking the date, but still have the flexibility over what should be ran when it's time to notify a user.
+
+## How does it work?
+With the power of cron, you set up a daily cron-job, e.g. at 8 AM, which will check if any of the people whose birthdays have been entered is close to their birthday.  Then, a script of yours gets passed some arguments and is executed.  What you do with this data is up to you.
+People willing to get notified can request additional reminders, for example 3 days before a birthday.  By default, only on the day of the birthday a notification is sent.  This is configurable in the `list.toml` file.
+
+## Sample config
+A sample config has been put into `list.example.toml`.
+Here's an excerpt:
+
+```
+preferences = [
+	{user="bob@localhost",   channels=[0]},
+	{user="alice@localhost", channels=[0], "additional_reminders"=[1, 7]}
+]
+
+birthdays = [
+	{name="Bob",   date="2000-01-01", to_notify=["alice@localhost"]},
+	{name="Alice", date="2000-01-23", to_notify=["bob@localhost"]}
+]
+
+actions = [
+	{id=0, name="print information", name_of_script="sample_script.py", startup_function="print_v1_data"}
+]
+```
+
+Above allows Bob to receive notifications about Alice's birthdays, and Alice to get reminded about Bob's birthday on the day of his birthday, but also 1 and 7 days prior.
+When they're meant to be notified, a method inside `sample_script.py` (in the `scripts` directory) called `print_v1_data` will be ran, with the API version and appropriate data passed.
+For API version "v1" these are: notifyee's username, name of the person, age, days until birthday (0 if it's the day of the birthday), and birthday date.
+
+For the cron job, a sample config would look something like:
+```
+0 7 * * * python3 /path/to/stolat/notify.py
+```
+This would make it run every day at 7 o'clock every day.
+It's important to make it run once per day, otherwise users will get notified as many times, as the script is run!