diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..4d4e08d
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,32 @@
+# Mandel-6502
+
+Work-in-progress Mandelbrot fractal viewer for Atari 8-bit home computers. Mostly an excute to write an integer multiplication routine for the 6502 for practice.
+
+Goals:
+* have fun learning 6502 assembly
+* make an old machine do something inefficient as efficiently as possible.
+* post cool screenshots of low-res fractals
+
+Non-goals:
+* maintain anything long-term (but feel free to copy/fork if you want to make major changes!)
+
+Enjoy! I'll probably work on this off and on for the next few weeks until I've got it producing fractals.
+
+-- brion, january 2023
+
+
+## Current state
+
+The 16-bit signed integer multiplication seems to be working, though I need to double-check it some more. It takes two 16-bit inputs and emits one 32-bit output in the zero page, using the Atari OS ROM's floating point registers as workspaces. Inputs are clobbered.
+
+The main loop is a basic add-and-shift, using 16-bit adds which requires flipping the sign of negative inputs (otherwise you'd have to add all those sign-extension bits). Runs in circa 450-750 cycles depending on input (I'll run the exact numbers again later).
+
+The mandelbrot loop is partly sketched out but I have future updates to make on that.
+
+I've also sketched out a 16-bit rounding macro, which is not yet committed.
+
+## Deps and build instructions
+
+I'm using `ca65` as a macro assembler, and have a Unix-style `Makefile` for building. Should work fairly easily on Linux and Mac. Might work on "raw' Windows but I use WSL for that.
+
+Currently produces a `.xex` executable, which can be booted up in common Atari emulators and some i/o devices.