pointers

specs.md

@@ -223,6 +223,50 @@ word := msg[6..11];  // string → "world"
 - Result type: `[]T` for arrays/slices, `string` for strings
 - No memory allocation — the result points into the original backing storage
 
+### Pointer Types
+
+| Syntax | Meaning | `.len` | `[i]` |
+|--------|---------|--------|-------|
+| `*T` | pointer to one T | no | no |
+| `[*]T` | many-pointer (buffer) | no | yes |
+| `*[N]T` | pointer to array of N T | yes | yes |
+| `*[]T` | pointer to slice | yes | yes |
+
+**Address-of**: `&x` returns a pointer to the variable.
+```sx
+v := Vec2.{ 1.0, 2.0 };
+ptr := &v;             // *Vec2
+```
+
+**Dereference**: `p.*` loads the value through the pointer.
+```sx
+copy := ptr.*;          // Vec2
+```
+
+**Auto-deref**: `p.field` is sugar for `p.*.field`.
+```sx
+set_x :: (p: *Vec2, val: f32) {
+    p.x = val;          // auto-deref: p.*.x = val
+}
+set_x(&v, 99.0);
+```
+
+**Null**: All pointer types are nullable. `null` is the null pointer literal.
+```sx
+np : *Vec2 = null;
+```
+
+**Many-pointer**: `[*]T` supports indexing for buffers of unknown size.
+```sx
+arr : [5]s32 = .[10, 20, 30, 40, 50];
+mp : [*]s32 = &arr[0];   // *s32 → [*]s32 implicit
+val := mp[2];             // 30
+```
+
+**Implicit conversions**:
+- `*T` → `[*]T` (pointer to element → many-pointer)
+- `null` (`*void`) → any `*T`
+
 ### Vector Types (SIMD)
 LLVM SIMD vectors, parameterized by length and element type.
 ```sx