1 files changed, 81 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..59a7e04
--- /dev/null
+++ b/README.md
@@ -0,0 +1,81 @@
+# esheep-wayland
+
+A Wayland desktop pet — the classic eSheep, ported to run as a
+wlr-layer-shell overlay on wlroots-based compositors (Wayfire, Sway,
+Hyprland, etc.).
+
+The sheep wanders along the bottom of your screen, climbs on top of
+open windows, gets abducted by UFOs, and can be picked up and dragged
+anywhere with the mouse.
+
+## Requirements
+
+- A wlroots compositor with `wlr-layer-shell` support (Wayfire, Sway, Hyprland, …)
+- Python 3.8+
+- `gtk3`
+- `gtk-layer-shell`
+- Python packages: `pygobject`, `pycairo`, `Pillow`, `numpy`
+- For window-top landing: the [pywayfire](https://github.com/WayfireWM/pywayfire) package and the `ipc` + `ipc-rules` Wayfire plugins enabled
+
+### Install Python dependencies
+
+```bash
+pip install pygobject pycairo Pillow numpy wayfire
+```
+
+### Enable Wayfire IPC (for window detection)
+
+In `~/.config/wayfire.ini`, add `ipc` and `ipc-rules` to your plugins line:
+
+```ini
+[core]
+plugins = ... ipc ipc-rules ...
+```
+
+Then restart Wayfire.
+
+## Installation
+
+```bash
+# Copy files into place
+mkdir -p ~/.local/share/esheep ~/.local/bin
+cp esheep.py animations.xml ~/.local/share/esheep/
+cp bin/esheep ~/.local/bin/esheep
+chmod +x ~/.local/bin/esheep
+
+# Optional: install the .desktop entry
+cp esheep.desktop ~/.local/share/applications/
+```
+
+## Usage
+
+```bash
+esheep               # one sheep
+esheep --count 3     # three sheep
+```
+
+### Click-to-drag
+
+Left-click the sheep and drag him anywhere on screen. Release and he
+falls back to the nearest surface below him.
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--xml PATH` | `animations.xml` next to the script | Path to animations XML |
+| `--count N` | `1` | Number of sheep to spawn |
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `esheep.py` | Main script |
+| `animations.xml` | Sprite sheet and animation state machine (original eSheep format) |
+| `bin/esheep` | Shell launcher |
+| `esheep.desktop` | XDG desktop entry |
+
+## Credits
+
+- Original eSheep concept and animations by [Adriano Petrucci](https://esheep.petrucci.ch/)
+- Wayland port and click-to-drag by ken + Claude