diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3f37011
--- /dev/null
+++ b/README.md
@@ -0,0 +1,79 @@
+
+# vc4
+
+**virtual computer 4** (see [vc3](https://git.sfja.dk/sfja/vc4) and [vc2](https://github.com/simonFJ20/vc2))
+
+a computer-emulator with custom architecture, and some stuff to write and run software on it.
+
+## goals
+
+- [ ] assemble program on host
+- [ ] run program from host
+- [ ] run program from emulated disk
+- [ ] output to monitor device
+- [ ] input from keyboard device
+- [ ] command shell
+- [ ] read/write files on emulated disk
+- [ ] host/vm file share
+- [ ] run programs from emulated disk
+- [ ] edit text files
+- [ ] assemble program on vm
+
+## isa
+
+- 16-bit instruction set
+- big endian
+
+### registers
+
+```
+r0      accumulator / return value
+r1
+r2
+r3
+r4
+r5
+r6
+sp      stack pointer
+bp      base pointer
+```
+
+### instructions
+
+```
+r   = register
+i16 = 16-bit immediate
+m   = memory [r/i16]
+
+nop
+hlt
+jmp     r/i16
+jnz     r/i16
+cmp     r/i16
+mov     r/i16/m r
+mov     r       r/i16/m
+in      r/i16
+out     r/i16   r/i16
+call    r/i16
+ret
+lit     r/i16
+int     i8
+
+or      r       r/i16
+xor     r       r/i16
+and     r       r/i16
+shl     r       r/i16
+rshl    r       r/i16
+shr     r       r/i16
+rshr    r       r/i16
+add     r       r/i16
+sub     r       r/i16
+rsub    r       r/i16
+mul     r       r/i16
+imul    r       r/i16
+div     r       r/i16
+idiv    r       r/i16
+mod     r       r/i16
+rmod    r       r/i16
+``` 
+