Add README, launcher script, and .desktop entry

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

3 files changed, 96 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
diff --git a/bin/esheep b/bin/esheep
new file mode 100755
index 0000000..91ba00e
--- /dev/null
+++ b/bin/esheep
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+exec python3 "$HOME/.local/share/esheep/esheep.py" \
+     --xml "$HOME/.local/share/esheep/animations.xml" "$@"
diff --git a/esheep.desktop b/esheep.desktop
new file mode 100644
index 0000000..5df0afd
--- /dev/null
+++ b/esheep.desktop
@@ -0,0 +1,12 @@
+[Desktop Entry]
+Version=1.0
+Type=Application
+Name=eSheep
+GenericName=Desktop Pet
+Comment=Wayland desktop sheep — wanders your screen, lands on windows, survives UFOs
+Exec=esheep
+Icon=esheep
+Terminal=false
+Categories=Amusement;
+Keywords=sheep;pet;desktop;wayland;fun;
+StartupNotify=false