From 960ca4489aebc263e9df43c58d703d54a2bd8f3b Mon Sep 17 00:00:00 2001
From: candifloss <candifloss@candifloss.cc>
Date: Thu, 18 Dec 2025 15:42:33 +0530
Subject: [PATCH] Update README - Description - Usage instructions - Config
 instructions - Install instructions - Requirements - Future plans - Notes

---
 README.md | 160 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 158 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 3add2d3..9488596 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,159 @@
-# icing
+# Icing: The sweet coating on your desktop 🍰
+
+**`icing`** is a small, fast X11 wallpaper setter written in Rust.
+
+It sets a wallpaper directly on the X11 root window, without daemons, background services, or unnecessary dependencies.
+Configuration is optional, and the app exits immediately after setting the wallpaper.
+
+---
+
+## Features
+
+* Simple CLI usage
+* Optional config file
+* Two image scaling modes: **Fill** and **Stretch**
+* Minimal dependencies
+* X11 only (Wayland not supported)
+
+---
+
+## Usage
+
+### Set wallpaper once (no config change)
+
+```sh
+icing --set /path/to/image.png
+```
+
+Sets the wallpaper immediately but does **not** update the config file.
+
+---
+
+### Update config and set wallpaper
+
+```sh
+icing --update /path/to/image.png
+```
+
+* Writes the image path to the config file
+* Sets the wallpaper immediately
+* Future runs of `icing` will reuse this image
+
+---
+
+### Use config only
+
+```sh
+icing
+```
+
+Uses the image path and settings from the config file.  
+Fails if no config exists.  
+
+---
+
+### Optional arguments
+
+```sh
+--mode fill|stretch
+```
+
+Overrides the default or configured scaling mode (see below).
+
+---
+
+## Configuration
+
+Config file location:
+
+```text
+~/.config/candywidgets/icing/config.toml
+```
+
+Example config:
+
+```toml
+background_image = "/path/to/image.png"
+mode = "fill"
+```
+
+### Config options
+
+| Key                | Description                        |
+| ------------------ | ---------------------------------- |
+| `background_image` | Path to the wallpaper image        |
+| `mode`             | Scaling mode (`fill` or `stretch`) |
+
+If `mode` is missing, **`fill` is used by default**.
+
+Invalid modes cause `icing` to exit with an error.
+
+---
+
+## Scaling modes
+
+| `fill` (default)                | `stretch`                                |
+| ------------------------------- | ---------------------------------------- |
+| Covers the entire screen        | Covers the entire screen                 |
+| Aspect ratio preserved          | Aspect ratio not preserved               |
+| Excess image cropped (centered) | Image may be stretched and distorted     |
+| Best choice for most wallpapers | Useful for exact fits or abstract images |
+
+---
+
+## Installation
+
+### Build from source
+
+```sh
+git clone https://git.candifloss.cc/candifloss/icing.git
+cd icing
+cargo build --release
+```
+
+Binary will be located at:
+
+```text
+target/release/icing
+```
+
+Optionally move it to your `$PATH` (for example `/usr/bin/`) if desired.
+
+---
+
+## Requirements
+
+* X11 (Xorg)
+* A window manager
+* Rust (for building)
+
+---
+
+## Future plans
+
+* Multi-monitor support via `--monitor <MONITOR>`
+
+  ```sh
+  icing --monitor HDMI-1 --set image.png
+  icing --monitor HDMI-2 --set image2.jpg --mode stretch
+  ```
+
+* Probably not:
+
+  * Additional scaling modes (unless they make sense)
+  * Wayland support
+
+---
+
+## Notes
+
+* `icing` does not run in the background
+* No daemon, no config watcher
+* Intended to be called explicitly (startup scripts, keybindings, etc.)
+
+---
+
+## License
+
+GPL-3.0-or-later
 
-Wallpaper setter
\ No newline at end of file