docs: add variables.md; tests: comprehensive assignment operator tests

- Document all assignment operators (:=, =:, =) with syntax table
- Document variable management commands (vars, clear, d)
- Document variable lifecycle and practical use cases
- Add table-driven tests for := and =: operators
- Add tests for = with expression continuation
- Add tests for variable reuse in expressions
- Add tests for chained assignments
- Add tests for vars/clear commands
- Add tests for d (delete) operator
- Add tests for variable persistence across expressions

1 files changed, 176 insertions, 0 deletions

diff --git a/docs/variables.md b/docs/variables.md
new file mode 100644
index 0000000..60474cc
--- /dev/null
+++ b/docs/variables.md
@@ -0,0 +1,176 @@
+# Variables and Assignment Operators
+
+The gt calculator supports named variables that store numeric values. Variables persist across expressions within a single RPN session (REPL or multi-expression input), enabling reusable values and multi-step calculations.
+
+## Assignment Operators
+
+Three assignment operators are available, differing in token order:
+
+| Operator | Syntax | Description | Example |
+|----------|--------|-------------|---------|
+| `:=` | `name value :=` | Right assignment | `x 5 :=` → `x = 5` |
+| `=:` | `value name =:` | Left assignment | `10 y =:` → `y = 10` |
+| `=` | `name value =` or `name = value` | Standard assignment | `x 10 =` or `x = 10` |
+
+### `:=` (Right Assignment)
+
+The value appears on the right (top of stack). This is the most idiomatic RPN form.
+
+```
+x 5 :=          → x = 5
+price 9.99 :=   → price = 9.99
+```
+
+### `=:` (Left Assignment)
+
+The value appears on the left (bottom of stack). Useful when you think in "value first" order.
+
+```
+42 answer =:    → answer = 42
+3.14159 pi =:   → pi = 3.14159
+```
+
+### `=` (Standard Assignment)
+
+Supports both infix-style (`name = value`) and postfix-style (`name value =`) syntax. Also supports expression continuation — you can append an expression after the assignment to evaluate immediately.
+
+```
+x = 5           → x = 5
+x 10 =          → x = 10
+x 10 = x 5 +    → 15  (assigns x=10, then evaluates x+5)
+```
+
+## Variable Management
+
+### `vars` — List Variables
+
+Shows all defined variables, sorted alphabetically with their values.
+
+```
+vars
+→ No variables defined          (when none exist)
+→ a = 10
+  b = 3                         (when variables are defined)
+```
+
+### `clear` — Clear All Variables
+
+Removes all defined variables at once.
+
+```
+clear
+→ All variables cleared
+```
+
+### `d` — Delete a Variable
+
+Removes a single variable. The variable name must be pushed as a symbol (using `:` prefix) onto the stack before `d`.
+
+```
+x 5 :=            → x = 5
+:x d              → (deletes x)
+x                 → :x    (x is now undefined, shown as symbol)
+```
+
+Attempting to delete a non-existent variable returns an error:
+
+```
+:nonexistent d    → error: variable not found: nonexistent
+```
+
+## Variable Lifecycle
+
+1. **Creation**: A variable is created when a value is assigned using `:=`, `=:`, or `=`.
+2. **Usage**: Reference the variable by name in an expression; its value is pushed onto the stack.
+3. **Reassignment**: Assigning to an existing variable overwrites its previous value.
+4. **Deletion**: Remove with `:name d` or clear all with `clear`.
+5. **Session scope**: Variables persist only within a single RPN session. Each CLI invocation starts fresh.
+
+## Using Variables in Expressions
+
+Once defined, variables are used by name in expressions. The variable's value is pushed onto the stack for computation.
+
+### Single Variable Reuse
+
+```
+x 5 :=
+x x +         → 10
+x 2 *         → 10
+```
+
+### Multi-Variable Expressions
+
+```
+a 10 :=
+b 3 :=
+a b +         → 13
+a b *         → 30
+```
+
+### Chained Assignments
+
+Multiple variables can be assigned in a single expression:
+
+```
+a 10 := b 3 := c 2 :=
+a b + c *     → 26
+```
+
+### Variable Reassignment
+
+Variables can be reassigned to new values:
+
+```
+x 5 :=          → x = 5
+x 10 :=         → x = 10
+x               → 10
+```
+
+### Assignment with Expression Continuation
+
+The `=` operator supports evaluating an expression immediately after assignment:
+
+```
+x 10 = x 5 +    → 15   (assigns x=10, then computes x+5)
+```
+
+## Practical Use Cases
+
+### Storing Reusable Values
+
+Store constants or frequently-used values to avoid retyping:
+
+```
+pi 3.14159265 :=
+radius 7 :=
+2 pi radius *          → 43.9822971   (circumference)
+```
+
+### Multi-Step Calculations
+
+Break complex calculations into named intermediate steps:
+
+```
+base 100 :=
+tax_rate 0.08 :=
+tax base tax_rate *    → 8
+total base tax +       → 108
+```
+
+### Iterative Refinement
+
+Update a running value across multiple operations:
+
+```
+sum 0 :=
+sum 10 +               → 10
+sum 20 +               → 30
+sum 5 -                → 25
+```
+
+## Reference
+
+- **Implementation**: `internal/rpn/operations_variables.go` (assignment operators, variable CRUD)
+- **Parsing**: `internal/rpn/rpn_parse.go` (`handleAssignmentOp()`, `handleStandardAssign()`)
+- **Registry**: `internal/rpn/operator_registry.go` (operator registration for `:=`, `=:`, `=`, `d`)
+- **Variable store**: `internal/rpn/variables.go` (thread-safe variable storage with save/load)