From 0d7dfde9265f9ceb4a8ab55f7063984b6df22141 Mon Sep 17 00:00:00 2001
From: candifloss <candifloss@candifloss.cc>
Date: Fri, 12 Dec 2025 16:33:44 +0530
Subject: [PATCH] Update README - Description - Installation instructions -
 Usage guide

---
 README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 82 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 23e9398..8684d81 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,83 @@
-# popcorn
+# Popcorn
+
+Minimal, fast, configurable OSD popup renderer for Linux.  
+Designed for use with lightweight desktops.  
+
+Popcorn shows a small on-screen popup for events like volume, brightness, or battery changes.  
+It is a **one-shot renderer**: other daemons or scripts call this binary with values and Popcorn displays the popup and exits.  
+
+Popcorn uses **Slint** for rendering and supports complete styling through a simple TOML configuration file.  
+
+
+## Features
+
+- Extremely lightweight and fast  
+- Works perfectly on tiling WMs  
+- Fully configurable  
+- Unicode glyphs as icons: Works well with Nerd Fonts.
+- Designed to be triggered by scripts, daemons, or key-bindings.  
+- CLI-supplied dynamic values (icon, percent, colors)  
+- Config-supplied static styling (size, fonts, colors, position, padding, timeout)  
+- Resolution-independent placement  
+
+
+## Installation
+
+Install using cargo:  
+```
+cargo install --git https://git.candifloss.cc/candifloss/popcorn.git popcorn
+```
+
+Optionally move the binary into your `$PATH`:  
+```
+sudo mv ~/.cargo/bin/popcorn /usr/bin/
+```
+
+## Usage
+
+Popcorn is typically invoked by a system daemon, widget, or window manager keybindings. Configure your app or WM keybinding to execute:  
+```
+popcorn --value={percent_value} --icon="{osd_icon}" --color="{hex_color_string}"
+```  
+
+### Arguments
+
+| Option               | Description                                                                                |
+| -------------------- | ------------------------------------------------------------------------------------------ |
+| `--value <PERCENT>`  | Percentage value for the popup (0 to 100). Used for volume, brightness, battery, etc. |
+| `--icon <GLYPH>`     | UTF-8 icon glyph. Nerd Fonts recommended.                                      |
+| `--color <AARRGGBB>` | Fill color. If omitted, config fallback is used.                                  |
+
+### Example calls
+
+#### Volume change
+
+```
+popcorn --value=45 --icon="" --color="ff55aaff"    # Normal volume: Bluish color.
+```
+
+#### Brightness change
+
+```
+popcorn --value=80 --icon="󰃟"   # No color specified. Falls back to default.
+```
+
+#### Battery status
+
+```
+popcorn --value=20 --icon="󰁼" --color="ffcc4444"    # Low battery: Reddish color.
+```
+
+## Configiration  
+
+See the [configuration guide](config.md).
+
+
+## License
+
+This project is licensed under the **GNU General Public License (GPL) version 3 or later**. You can redistribute it and/or modify it under the terms of this License.
+
+This software is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the **GNU General Public License** for more details.
+
+For a copy of the full license, see the [LICENSE](LICENSE) file in the project repository.
 
-Simple OSD popups for your desktop
\ No newline at end of file