diff --git a/README.md b/README.md
index 4306c1d..c6864d9 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,17 @@
-## What is processor?
-processor is an implementation of the hypothetical machine that runs Vole machine language presented in [Computer Science: An Overview by J. Glenn Brookshear](https://books.google.com.tr/books/about/Computer_Science.html?id=bVctyQEACAAJ&source=kp_book_description&redir_esc=y "Google Books link")
+# vole
+
+A Windows Forms simulator for the hypothetical Vole machine from *Computer Science: An Overview* by J. Glenn Brookshear. Lets you write Vole programs, load them into simulated RAM, and step through or run execution while watching registers and memory update in real time.
+
+12 opcodes total. 9 are implemented (load/store, move, integer add, bitwise OR/AND/XOR, halt). Floating-point addition (0x6), rotate (0xA), and conditional jump (0xB) are stubs. Binary mode loading is also not implemented.
+
+## how to get it up
+
+Requires .NET 5 on Windows (WinForms).
+
+```
+dotnet run --project src/processor.csproj
+```
+
+Write programs in the code editor using the `.vole` format — see `examples/` for reference. Lines prefixed `0x` are CPU instructions loaded into RAM; lines prefixed `1x` write data directly to RAM addresses. Comments start with `#`.
+
+yigid balaban, 2021