docs: add project README

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I45a3fa9e4f1c8758b65e119e16e7b8a16a6a6964

README.md

@@ -0,0 +1,160 @@
+# Sin
+
+> 🙏 Forgive me father for I have simply inhibited.
+
+**S**imple **In**hibitor (Sin) watches `/proc` for processes matching your
+patterns and inhibits system idle/sleep while they run.
+
+## Why
+
+Your system shouldn't sleep while you're watching a movie, compiling code, or
+running a long task. Sin prevents that by talking to systemd-logind when your
+processes are active.
+
+I think this is should be a part of the idle program itself, but I could not
+find an idle daemon that supports this feature. Naturally I made one of my own.
+You are welcome to use it if this fits your needs. It is easy to **S**imply
+**In**hibit.
+
+This is an _alternative_ to handling inhbiting on a compositor level, and is
+aimed to detect things a compositor generally cannot. In the case of, e.g.,
+desktop applications I recommend letting your compositor handling the inhibit. I
+might also support this for Sin in the future.
+
+## How it works
+
+1. You tell Sin which processes to watch (e.g., `mpv`, `steam`, `ffmpeg`)
+2. Sin scans `/proc` every few seconds looking for them
+3. When found, it grabs a Systemd inhibitor lock
+4. When they exit, it releases the lock
+5. Your system can sleep again
+
+Great success!
+
+## Usage
+
+```bash
+# Keep system awake while Firefox is running
+sin -n firefox
+
+# Watch multiple processes
+sin -n steam -n "wine " -n lutris
+
+# Prevent sleep (not just idle) while rendering
+sin -n blender --what=sleep
+
+# Custom poll interval
+sin -n mpv --poll=1.0
+```
+
+### Options
+
+```plaintext
+-n, --name PATTERN     Process cmdline substring to watch (required, repeatable)
+--what WHAT           What to inhibit: idle, sleep, shutdown, etc. (default: idle)
+--mode MODE           block or delay (default: block)
+--poll SECONDS        How often to check (0.1-3600, default: 2.0)
+-d, --daemon          Run as daemon (fork to background)
+-q, --quiet           Suppress informational output
+-v, --version         Show version
+-h, --help            Show help
+```
+
+## Building
+
+```bash
+make
+sudo make install
+```
+
+Requires:
+
+- GCC or Clang
+- libsystemd
+
+That's it.
+
+## Examples
+
+```bash
+# Don't idle while gaming
+sin -n steam -n wine
+
+# Keep system awake during long builds
+sin -n "cargo build" -n "nix build"
+
+# Prevent sleep while watching videos
+sin -n mpv -n vlc --what=sleep
+
+# Fast polling for responsive tasks
+sin -n ffmpeg --poll=0.5
+
+# Run as daemon
+sin -d -n mpv -n vlc
+```
+
+## Running as a Service
+
+A systemd service file is provided in `vendor/sin.service`. Edit it to match
+your needs:
+
+```bash
+# Copy and customize the service file
+sudo cp vendor/sin.service /etc/systemd/system/
+sudo nano /etc/systemd/system/sin.service  # Edit the ExecStart line
+
+# Enable and start
+sudo systemctl enable --now sin.service
+```
+
+## Why not just use...?
+
+### Systemd-inhibit
+
+There are a few alternative options that you could go with. Namely, Sin is
+inspired by the operating principle of `systemd-inhibit` among those options,
+but prefers an approach similar to EarlyOOM where you provide the programs that
+you want to watch instead of launching the program with a systemd-inhibit
+wrapper.
+
+### Caffeine
+
+While researching, I've noticed programs such as **caffeine** and
+**caffeine-ng** but ultimately decided against those since they seem to be
+hooking up to more specific APIs than Systemd's own. I also find Python to be
+unsuitable for production, and have elected to use C for a smaller and faster
+binary that is easier to bootstrap.
+
+If you _do_ use those tools, and would like to try out Sin but cannot make a
+switch due to missing features, please do create an issue. While I do not wish
+to support screenlocker-specific APIs, I am happy to implement more generic
+features such as a tray icon. Maybe even support for other init systems in the
+future.
+
+### Hand-written Systemd Service
+
+Sure, if you'd like to write one yourself. Sin is that Systemd service in my
+case. Give it a try, maybe I've saved you from some code spent fixing a trivial
+problem.
+
+## Attributions
+
+[Diniamo]: https://github.com/diniamo
+[Wayhibit]: https://github.com/diniamo/wayhibitor
+
+This project was inspired partially by [Diniamo]'s [Wayhibit], which deserves
+the primary attribution here. I'd also like to thank Systemd developers for
+`systemd-inhibit`, which has inspired me to write this project and also for the
+sd-bus API that makes Sin possible.
+
+## License
+
+<!-- markdownlint-disable MD059 -->
+
+[here]: https://interoperable-europe.ec.europa.eu/sites/default/files/custom-page/attachment/eupl_v1.2_en.pdf
+
+This project is made available under European Union Public Licence (EUPL)
+version 1.2. See [LICENSE](LICENSE) for more details on the exact conditions. An
+online copy is provided [here].
+
+<!-- markdownlint-enable MD059 -->