Refresh control-flow and error docs for loop semantics

Author: mgomes

ROADMAP.md

@@ -232,7 +232,7 @@ Goal: improve language ergonomics for complex script logic and recovery behavior
 
 - [x] Add parser/runtime tests for each new control flow construct.
 - [x] Add nested control flow tests for edge cases.
-- [ ] Add docs updates in `docs/control-flow.md` and `docs/errors.md`.
+- [x] Add docs updates in `docs/control-flow.md` and `docs/errors.md`.
 - [ ] Add examples under `examples/control_flow/` for each new feature.
 
 ### v0.16.0 Definition of Done

docs/control-flow.md

@@ -1,27 +1,74 @@
 # Control Flow and Ranges
 
-VibeScript supports familiar Ruby control structures:
+VibeScript supports these control-flow forms:
 
-- `if/elsif/else` expressions
-- `for` loops iterating arrays or ranges
-- Numeric ranges via `start..finish`
+- `if` / `elsif` / `else`
+- `for` loops over arrays and ranges
+- `while` and `until` loops
+- loop control with `break` and `next`
+- numeric ranges via `start..finish`
 
-Example range usage:
+## `for` loops
 
 ```vibe
-def fizzbuzz(limit)
-  for n in 1..limit
-    if n % 15 == 0
-      puts("FizzBuzz")
-    elsif n % 3 == 0
-      puts("Fizz")
-    elsif n % 5 == 0
-      puts("Buzz")
-    else
-      puts(n)
+def sum_first_five()
+  total = 0
+  for n in 1..5
+    total = total + n
+  end
+  total
+end
+```
+
+## `while` and `until`
+
+```vibe
+def countdown(n)
+  out = []
+  while n > 0
+    out = out + [n]
+    n = n - 1
+  end
+  out
+end
+
+def count_up(limit)
+  out = []
+  n = 0
+  until n >= limit
+    out = out + [n]
+    n = n + 1
+  end
+  out
+end
+```
+
+## `break` and `next`
+
+```vibe
+def odds_under_five()
+  out = []
+  for n in [1, 2, 3, 4, 5]
+    if n == 5
+      break
     end
+    if n % 2 == 0
+      next
+    end
+    out = out + [n]
   end
+  out
 end
 ```
 
-See `examples/loops/` and `examples/ranges/` for runnable scripts.
+Semantics:
+
+- In nested loops, `break` and `next` target the nearest active loop.
+- `break`/`next` used outside any loop raise runtime errors.
+- `break`/`next` cannot cross call boundaries (for example from block callbacks back into outer loops).
+
+## Quotas
+
+Loop execution participates in step and memory quotas. Infinite loops will terminate with quota errors when limits are exceeded.
+
+See `examples/control_flow/`, `examples/loops/`, and `examples/ranges/` for runnable scripts.

docs/errors.md

@@ -37,6 +37,31 @@ division by zero
   at calculate (7:7)
 ```
 
+## Type Errors
+
+Typed argument and return checks include:
+
+- parameter or function context
+- expected type
+- actual runtime type
+
+```text
+argument payload expected { id: string, score: int }, got { id: string, score: string }
+```
+
+For composite values, actual types include shape/element detail (`array<int | string>`, `{ id: string, ... }`) to make fixes local and explicit.
+
+## Loop Control Errors
+
+Loop control diagnostics are explicit:
+
+- `break used outside of loop`
+- `next used outside of loop`
+- `break cannot cross call boundary`
+- `next cannot cross call boundary`
+
+These boundary errors happen when `break`/`next` are raised inside called blocks/functions and attempt to escape into an outer loop.
+
 ## REPL Debugging
 
 The REPL stores the previous failure. Use: