diff --git a/src/opcode.ts b/src/opcode.ts
index 098183b..9bc272a 100644
--- a/src/opcode.ts
+++ b/src/opcode.ts
@@ -1,65 +1,65 @@
 export enum OpCode {
   // stack
-  PUSH,  // operand: constant index (number)
-  POP,   // operand: none
-  DUP,   // operand: none
+  PUSH,  // operand: constant index (number) | stack: [] → [value]
+  POP,   // operand: none | stack: [value] → []
+  DUP,   // operand: none | stack: [value] → [value, value]
 
   // variables
-  LOAD,  // operand: variable name (string)
-  STORE, // operand: variable name (string)
+  LOAD,  // operand: variable name (identifier) | stack: [] → [value]
+  STORE, // operand: variable name (identifier) | stack: [value] → []
 
-  // math
-  ADD,
-  SUB,
-  MUL,
-  DIV,
-  MOD,
+  // math (coerce to number, pop 2, push result)
+  ADD,   // operand: none | stack: [a, b] → [a + b]
+  SUB,   // operand: none | stack: [a, b] → [a - b]
+  MUL,   // operand: none | stack: [a, b] → [a * b]
+  DIV,   // operand: none | stack: [a, b] → [a / b]
+  MOD,   // operand: none | stack: [a, b] → [a % b]
 
-  // comparison
-  EQ,
-  NEQ,
-  LT,
-  GT,
-  LTE,
-  GTE,
+  // comparison (pop 2, push boolean)
+  EQ,    // operand: none | stack: [a, b] → [a == b] (deep equality)
+  NEQ,   // operand: none | stack: [a, b] → [a != b]
+  LT,    // operand: none | stack: [a, b] → [a < b] (numeric)
+  GT,    // operand: none | stack: [a, b] → [a > b] (numeric)
+  LTE,   // operand: none | stack: [a, b] → [a <= b] (numeric)
+  GTE,   // operand: none | stack: [a, b] → [a >= b] (numeric)
 
   // logical
-  NOT,
+  NOT,   // operand: none | stack: [a] → [!isTrue(a)]
 
   // control flow
-  JUMP,
-  JUMP_IF_FALSE,
-  JUMP_IF_TRUE,
-  BREAK,
+  JUMP,           // operand: relative offset (number) | PC-relative jump
+  JUMP_IF_FALSE,  // operand: relative offset (number) | stack: [condition] → [] | jump if falsy
+  JUMP_IF_TRUE,   // operand: relative offset (number) | stack: [condition] → [] | jump if truthy
+  BREAK,          // operand: none | unwind call stack to break target
 
   // exception handling
-  PUSH_TRY,
-  PUSH_FINALLY,
-  POP_TRY,
-  THROW,
+  PUSH_TRY,      // operand: absolute catch address (number) | register exception handler
+  PUSH_FINALLY,  // operand: absolute finally address (number) | add finally to current handler
+  POP_TRY,       // operand: none | remove exception handler (try completed successfully)
+  THROW,         // operand: none | stack: [error] → (unwound) | throw exception
 
   // functions
-  MAKE_FUNCTION,
-  CALL,
-  TAIL_CALL,
-  RETURN,
+  MAKE_FUNCTION, // operand: function def index (number) | stack: [] → [function] | captures scope
+  CALL,          // operand: none | stack: [fn, ...args, posCount, namedCount] → [result] | marks break target
+  TAIL_CALL,     // operand: none | stack: [fn, ...args, posCount, namedCount] → [result] | reuses frame
+  RETURN,        // operand: none | stack: [value] → (restored with value) | return from function
 
   // arrays
-  MAKE_ARRAY,
-  ARRAY_GET,
-  ARRAY_SET,
-  ARRAY_PUSH,
-  ARRAY_LEN,
+  MAKE_ARRAY,  // operand: item count (number) | stack: [item1, ..., itemN] → [array]
+  ARRAY_GET,   // operand: none | stack: [array, index] → [value]
+  ARRAY_SET,   // operand: none | stack: [array, index, value] → [] | mutates array
+  ARRAY_PUSH,  // operand: none | stack: [array, value] → [] | mutates array
+  ARRAY_LEN,   // operand: none | stack: [array] → [length]
 
   // dicts
-  MAKE_DICT,
-  DICT_GET,
-  DICT_SET,
-  DICT_HAS,
+  MAKE_DICT,   // operand: pair count (number) | stack: [key1, val1, ..., keyN, valN] → [dict]
+  DICT_GET,    // operand: none | stack: [dict, key] → [value] | returns null if missing
+  DICT_SET,    // operand: none | stack: [dict, key, value] → [] | mutates dict
+  DICT_HAS,    // operand: none | stack: [dict, key] → [boolean]
 
   // typescript interop
-  CALL_NATIVE,
+  CALL_NATIVE, // operand: function name (identifier) | stack: [...args] → [result] | consumes entire stack
 
   // special
-  HALT
+  HALT         // operand: none | stop execution
 }
\ No newline at end of file