*

1 files changed, 49 insertions, 6 deletions

diff --git a/awk/vm/README.md b/awk/vm/README.md
index e6bd7a1..83a35fd 100644
--- a/awk/vm/README.md
+++ b/awk/vm/README.md
@@ -1,6 +1,6 @@
-# Simple Stack-Based Virtual Machine
+# Stack-Based Virtual Machine in AWK
 
-This is an implementation of a minimal stack-based virtual machine in AWK, inspired by Forth. The VM provides basic stack manipulation, arithmetic operations, register access, and memory operations.
+A simple stack-based virtual machine implementation in AWK, inspired by Forth. The VM provides basic stack manipulation, arithmetic operations, register access, and memory operations.
 
 ## Architecture
 
@@ -18,10 +18,12 @@ The VM consists of:
 - `DROP` - Remove top item from stack
 - `DUP` - Duplicate top stack item
 - `OVER` - Copy second item to top of stack
+- `SWAP` - Exchange top two stack items
 - Numbers are automatically pushed onto the stack
 
 ### Arithmetic Operations
 - `+` - Add top two stack items (a b -- a+b)
+- `*` - Multiply top two stack items (a b -- a*b)
 - `AND` - Bitwise AND of top two items
 - `XOR` - Bitwise XOR of top two items
 - `NOT` - Bitwise NOT of top item
@@ -34,8 +36,8 @@ The VM consists of:
 - `B!` - Store top stack value into B register
 
 ### Memory Operations
-- `@` - Fetch from memory address on stack
-- `!` - Store to memory address on stack
+- `@` - Fetch from memory address on stack (addr -- value)
+- `!` - Store to memory address on stack (value addr --)
 - `@+` - Fetch from memory at P, then increment P
 - `!+` - Store to memory at P, then increment P
 - `@B` - Fetch from memory address in B register
@@ -43,6 +45,47 @@ The VM consists of:
 - `@P` - Fetch from memory address in P register
 - `!P` - Store to memory address in P register
 
-### Utility
+### Debug & Control
 - `.` - NO-OP (does nothing)
-- `BYE` - Exit program
\ No newline at end of file
+- `BYE` - Exit program
+- `SHOW` - Display current machine state (stack, registers, memory)
+
+## Memory Model
+
+- Memory is zero-based
+- Each cell can hold a numeric value
+- Memory is accessed either directly (using @ and !) or through registers
+- P register is typically used for sequential memory operations
+- B register is typically used as a memory pointer
+
+## Example Programs
+
+### Store and retrieve a value
+```
+5 DUP 0 ! # Store 5 at address 0
+3 DUP 1 ! # Store 3 at address 1
+0 @ 1 @ + # Load both values and add them
+2 ! # Store result at address 2
+```
+
+### Using registers
+```
+42 A! # Store 42 in A register
+A # Push A's value onto stack
+100 B! # Set B to address 100
+42 !B # Store 42 at address 100
+@B # Read from address 100
+```
+
+## Usage
+
+```bash
+# Run a program directly
+echo "5 3 + SHOW" | awk -f vm.awk
+
+# Compile and run a program
+./compiler.py program.coffee | awk -f vm.awk
+
+# Run test suite
+./vm_tests.sh
+```
\ No newline at end of file