diff --git a/README.md b/README.md
index d6a3647..2dbc336 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,57 @@
 # pixsy
 
-convert images to rooms for use in Bitsy
+a tool for [Bitsy Game Maker](http://bitsy.org). 
+upload any image and convert it into a room.
+
+## credits
+
+made by [Max Bradbury](http://tinybird.info/). 
+makes use of my own [bitsy parser](https://crates.io/crates/bitsy-parser) library.
+
+uses the [Croppie](https://foliotek.github.io/Croppie/) image crop plugin 
+by [Foliotek](https://www.foliotek.com/)
+
+uses [wasm-bindgen](https://crates.io/crates/wasm-bindgen) to automate WebAssembly bindings.
+
+## thanks
+
+to [Adam Le Doux](http://ledoux.io/) for creating the wonderful and inspiring Bitsy
+
+to [Mark Wonnacott](https://kool.tools/) for their support, encouragement and inspiration
+
+and to everyone in the bitsy community!
+
+## contributing
+
+forks and pull requests welcome!
+
+### development prerequisites
+
+* [rust/cargo](https://rustup.rs/)
+* [pug](https://pugjs.org/)
+* [less](http://lesscss.org/)
+* a bash shell for the build script
+
+## bugs
+
+when importing images, some pixels have errors. 
+it seems to only happen for pixels surrounded at the top and left:
+```
+111    111
+100 => 110
+100    100
+```
+
+does not work in the Itch desktop program 
+because their bundled version of Chromium does not support WebAssembly.
+
+## to do
+
+* add alternative dithering options (Atkinson, Bayer 8×8)
+* add a 'smoothing' (noise reduction?) stage to remove errant pixels
+
+## could do
+
+* reimplement tile reuse option
+* add camera support so users can take a pic instead of uploading an image
+* allow user to draw to canvas
diff --git a/TODO.md b/TODO.md
deleted file mode 100644
index 7e5744d..0000000
--- a/TODO.md
+++ /dev/null
@@ -1,6 +0,0 @@
-# todo
-
-* tile reuse
-* noise reduction (remove lonely pixels)
-* implement Atkinson and Bayer dithering options
-* fix weird problem with pixels flipping (see test::example)