diff --git a/doc/README.md b/doc/README.md
index 288737d..67c33ee 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -11,3 +11,4 @@
 * [Load code in RAM and run it](load-run-code.md)
 * [Using block devices](blockdev.md)
 * [Using the filesystem](fs.md)
+* [Assembling z80 source from the shell](zasm.md)
diff --git a/doc/zasm.md b/doc/zasm.md
new file mode 100644
index 0000000..b32a4ec
--- /dev/null
+++ b/doc/zasm.md
@@ -0,0 +1,31 @@
+# Assembling z80 source from the shell
+
+In its current state, Collapse OS has all you need to assemble z80 source
+from within the shell. What you need is:
+
+* A mounted filesystem with `zasm` on it.
+* A block device to read from (can be a file from mounted CFS)
+* A block device to write to (can theoretically be a file, but technical
+  limitations temporary prevents us that. We'll use a mmap for now).
+
+The emulated shell is already set up with all you need. If you want to run that
+on a real machine, you'll have to make sure to provide these requirements.
+
+The emulated shell has a `hello.asm` file in its mounted filesystem that is
+ready to compile. It has two file handles 0 and 1, mapped to blk IDs 1 and 2.
+We only use file handle 0 (blk ID 1) and then tell zasm to output to mmap which
+is configured to start at `0xe00`
+
+    Collapse OS
+    > fopn 0 hello.asm      ; open file in handle 0
+    > zasm 1 3              ; assemble opened file and spit result in mmap
+    > bsel 3                ; select mmap
+    > peek 5
+    210890CD3C              ; looking good
+    > mptr 9000             ; hello.asm is configured to run from 0x9000
+    > load ff               ; load compiled code from mmap
+    > peek 5
+    210890CD3C              ; looking good
+    > call 00 0000
+    Assembled from the shell
+    >                       ; Awesome!
diff --git a/tools/emul/shell/shell_.asm b/tools/emul/shell/shell_.asm
index 49dc8a9..558fe86 100644
--- a/tools/emul/shell/shell_.asm
+++ b/tools/emul/shell/shell_.asm
@@ -1,7 +1,9 @@
 ; named shell_.asm to avoid infinite include loop.
 .equ	RAMSTART	0x4000
-.equ	KERNEL_RAMEND	0x5000
-.equ	USERCODE	0x9000
+; kernel ram is well under 0x100 bytes. We're giving us 0x200 bytes so that we
+; never worry about the stack.
+.equ	KERNEL_RAMEND	0x4200
+.equ	USERCODE	KERNEL_RAMEND
 .equ	STDIO_PORT	0x00
 .equ	FS_DATA_PORT	0x01
 .equ	FS_SEEKL_PORT	0x02
@@ -37,16 +39,21 @@
 #include "parse.asm"
 
 .equ	BLOCKDEV_RAMSTART	RAMSTART
-.equ	BLOCKDEV_COUNT		3
+.equ	BLOCKDEV_COUNT		4
 #include "blockdev.asm"
 ; List of devices
 .dw	fsdevGetC, fsdevPutC, fsdevSeek, fsdevTell
 .dw	stdoutGetC, stdoutPutC, stdoutSeek, stdoutTell
 .dw	stdinGetC, stdinPutC, stdinSeek, stdinTell
+.dw	mmapGetC, mmapPutC, mmapSeek, mmapTell
 
 #include "blockdev_cmds.asm"
 
-.equ	STDIO_RAMSTART	BLOCKDEV_RAMEND
+.equ	MMAP_RAMSTART	BLOCKDEV_RAMEND
+.equ	MMAP_START	0xe000
+#include "mmap.asm"
+
+.equ	STDIO_RAMSTART	MMAP_RAMEND
 #include "stdio.asm"
 
 .equ	FS_RAMSTART	STDIO_RAMEND
@@ -64,6 +71,8 @@
 .equ	PGM_CODEADDR		USERCODE
 #include "pgm.asm"
 
+.out	PGM_RAMEND
+
 init:
 	di
 	; setup stack
diff --git a/tools/emul/shell/user.h b/tools/emul/shell/user.h
index fc1f32e..14e388a 100644
--- a/tools/emul/shell/user.h
+++ b/tools/emul/shell/user.h
@@ -1,5 +1,5 @@
-.equ    USER_CODE       0x9000
-.equ    USER_RAMSTART   0xa800
+.equ    USER_CODE       0x4200
+.equ    USER_RAMSTART   USER_CODE+0x1800
 .equ    FS_HANDLE_SIZE  8
 
 ; *** JUMP TABLE ***