Add typing migration examples to documentation

Author: mgomes

docs/typing.md

@@ -72,6 +72,112 @@ Unknown keyword args and missing required args raise errors.
 
 If a return type is annotated, the returned value is checked. If omitted, no return check is enforced.
 
+## Migration examples
+
+Use a boundary-first strategy: annotate entrypoints that receive external data, then tighten helpers and block callbacks.
+
+### 1) Start with function boundaries
+
+Before:
+
+```vibe
+def calculate_total(items)
+  items.reduce(0) do |acc, item|
+    acc + item[:amount]
+  end
+end
+```
+
+After:
+
+```vibe
+def calculate_total(items: array<{ amount: int }>) -> int
+  items.reduce(0) do |acc: int, item: { amount: int }|
+    acc + item[:amount]
+  end
+end
+```
+
+### 2) Migrate optional values with nullable or unions
+
+Before:
+
+```vibe
+def normalize_id(id)
+  if id == nil
+    "unknown"
+  else
+    id.string
+  end
+end
+```
+
+After:
+
+```vibe
+def normalize_id(id: int | string | nil) -> string
+  if id == nil
+    "unknown"
+  else
+    id.string
+  end
+end
+```
+
+Use `T?` when the only optional case is `nil`, and use unions when multiple concrete kinds are allowed.
+
+### 3) Convert loose hashes to shape contracts
+
+Before:
+
+```vibe
+def reward(payload)
+  { id: payload[:id], points: payload[:points] + 10 }
+end
+```
+
+After:
+
+```vibe
+def reward(payload: { id: string, points: int }) -> { id: string, points: int }
+  { id: payload[:id], points: payload[:points] + 10 }
+end
+```
+
+Shapes are strict. Missing or extra keys fail checks.
+
+### 4) Annotate block signatures where callbacks matter
+
+Before:
+
+```vibe
+def render_scores(scores)
+  scores.map do |s|
+    s + 1
+  end
+end
+```
+
+After:
+
+```vibe
+def render_scores(scores: array<int>) -> array<int>
+  scores.map do |s: int|
+    s + 1
+  end
+end
+```
+
+Typed blocks catch callback mismatches at runtime with errors that include parameter name, expected type, and actual type.
+
+### 5) Roll out incrementally
+
+- Add annotations to one high-value path first.
+- Keep internal helpers untyped until boundary contracts stabilize.
+- Use `any` as a temporary bridge during migration.
+- Replace `any` with concrete or shape types once call sites are clean.
+- Watch runtime type errors in staging, then tighten signatures further.
+
 ## Time and Duration
 
 Duration methods like `ago`/`after` return `Time`. Typed signatures use `time` or `time?` for those values.