From 15c909d95421ca0c1352829bd5ec0bd0adcc75fe Mon Sep 17 00:00:00 2001
From: Hyperling <me@hyperling.com>
Date: Fri, 16 Oct 2026 09:07:56 -0700
Subject: [PATCH] Add design.

---
 README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 95 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index c466bbb..dea003b 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,96 @@
-# template-mit
+# Sunset Alarm (CLI)
 
-Template with MIT license, protected `main` branch, and available `dev` branch.
\ No newline at end of file
+Command line Sunset Alarm app which can be run as a user daemon.
+
+Sunset Alarm allows a user to receive an alert at a specified amount of minutes
+before sunset. This may be helpful for starting any practices such as preparing
+for sungazing, or as a reminder to go and find a campsite before it gets dark.
+
+## Usage
+
+() sections are required. [] sections are optional. | denotes multiple options.
+
+```console
+sunset-timer (-l LAT:LONG | -t HH24:MI) (-m MINUTES) [-h]
+```
+
+## Example
+
+Set an alarm 90 minutes before for your lat/long experiences sunset:
+
+```shell
+sunset-alarm -l 32.123:-111.111 -m 90
+```
+
+Set an alarm 5 minutes after a manually determined sunset time:
+
+```shell
+sunset-alarm -t 18:00 -m -5
+```
+
+## Install
+
+Recommended installation location is under `/usr/local/*`.
+
+```console
+# git clone http://git.hyperling.com/me/sunset-alarm-cli /usr/local/src/sunset_alarm_cli
+# ln -s /usr/local/src/sunset_alarm_cli/sunset-alarm /usr/local/bin/
+```
+
+### Daemonize
+
+**runit**
+
+Create the run file:
+
+```console
+# vi /etc/sv/sunset-alarm/run:
+```
+
+```shell
+#!/bin/sh -e
+exec 2>&1
+chpst -u user /usr/local/bin/sunset-alarm -l 33:-112 -m 15
+```
+
+Enable the service:
+
+```console
+# ln -s /etc/sv/sunset-alarm /var/services/
+```
+
+### i3
+
+Simply add an exec to the end of your config file.
+
+```shell
+echo "exec --no-startup-id /usr/local/bin/sunset-alarm -l 33:-112 -m 15" >> ~/.config/i3/config
+```
+
+## Parameters
+
+**Required**
+
+-m : Accepts a minute value which is used to check if we have approached the
+alert period before sunset. Can be positive, negative, or 0.
+
+**Optional**
+
+-l : Accepts a lat:long value which is used to check Open Meteo for the
+location's sunset time. This is required if -t is not passed.
+
+-t : Accepts a time value for sunset time. If this is passed, it bypasses the
+Open Meteo check and acts as a hardcoded time. The minutes parameter is still
+required to know when to alert prior to this time.
+
+## Design
+
+App displays a persistent alert via channels such as `fyi` or `notify-send` once
+the current time is between (sunset - minutes) and midnight. Even if the system
+is powered on after the alert time has passed, the program should display the
+alert until the day has passed.
+
+App requires an internet connection. If no connection is found, it sleeps for 5
+minutes and then tries again to retrieve the sunset time. Once the sunset time has
+been retrieved for the current day, it stops checking Open Meteo until the next
+day.