diff --git a/README.md b/README.md
new file mode 100644
index 0000000..28fee18
--- /dev/null
+++ b/README.md
@@ -0,0 +1,39 @@
+# imagey
+
+image viewer and maybe editor; inspired by mpv's simplicity
+
+name is subject to change, suggestions welcome :)
+
+## usage
+
+```sh
+# try it out!
+nix run git+https://git.federated.nexus/electria/imagey
+
+# install it imperatively
+nix profile install git+https://git.federated.nexus/electria/imagey
+```
+
+## known issues
+
+### JXL
+
+1. encoding is not implemented (jxl-oxide is decoding-only)
+2. oreintation is incorrect in some cases
+
+    if the image has metadata oreintation AND
+
+    it's a jxl without the right extension OR
+    it's a jpeg with the jxl extension
+
+    this is due to the JXL decoder automatically rotating the image,
+    while the JPEG decoder (for instance) requires the extra step.
+
+    my workaround is to check the path of the input file,
+    not changing the oreintation if it has the jxl extension;
+    causing these caveats for cases where the extension is wrong.
+
+### clipboard
+
+1. large images (eg photos) don't seem to copy on linux/wayland,
+    (despite set_image not returning any error)