docs: sync README and plans with v0.5.x features

Document multi-instance closures, tuples, Iter HOF, diagnostics, and
updated test targets. Refresh QUALITY_PLAN diagnosis and next-day backlog.

README.md

@@ -2,13 +2,15 @@
 
 ![Bux Language](bux-lang-01.jpeg)
 
-> **Status:** v0.5.0 — Bootstrap compiler (`buxc`, Nim) and self-hosted compiler (`buxc2`, Bux) both compile `.bux` → C → native binary.
+> **Status:** v0.5.x — Bootstrap (`buxc`, Nim) and self-hosted (`buxc2`, Bux) both compile `.bux` → C → native binary.
-> **Selfhost loop:** `buxc2` compiles itself → binary-identical `buxc3` ✅ Deterministic C codegen + ELF verified.
+> **Selfhost loop:** deterministic C codegen + ELF verified.
 > **Gradual Ownership:** `@[Checked]` borrow checker, `@[Release]` zero-cost mode, `borrow &mut` expressions.
+> **Closures:** multi-instance capturing closures via fat function pointers (`BuxFn { code, env }`) in both compilers.
+> **Tuples:** `(T, U)` types and `.0`/`.1` field access (bootstrap + selfhost).
 > **Green Threads:** M:N scheduler with channels (Go-style goroutines without GC).
-> **All 26 examples pass.** Compiler successfully parses all 3 real-world apps (`apps/boko-framework`, `apps/jwt-pitbul`, `apps/nexus`).
+> **Examples:** 40+ programs pass (`make test-examples`). Apps: `boko-framework`, `jwt-pitbul`, `nexus`, `simpledb`.
 
-Bux is a fast, compiled, strongly-typed systems programming language. Features a C backend for native code generation, raw multi-line strings, gradual ownership (opt-in borrow checking), async/await, generics, algebraic enums, and a package manager.
+Bux is a fast, compiled, strongly-typed systems programming language. Features a C backend for native code generation, raw multi-line strings, gradual ownership (opt-in borrow checking), multi-instance closures, async/await, generics, algebraic enums, and a package manager.
 
 ---
 
@@ -185,22 +187,55 @@ func Main() -> int {
 }
 ```
 
+### Multi-instance closures
+```bux
+func MakeAdder(base: int) -> func(int) -> int {
+    return |a: int| -> int { return a + base; };
+}
+
+func Main() -> int {
+    let a10 = MakeAdder(10);
+    let a20 = MakeAdder(20);
+    // Independent capture environments
+    PrintInt(a10(1));  // 11
+    PrintInt(a20(1));  // 21
+    return 0;
+}
+```
+
+### Iter map / filter / fold
+```bux
+import Std::Iter::{Array_Iter, Iter_MapInt, Iter_FilterInt, Iter_FoldInt};
+
+func Main() -> int {
+    var nums: Array<int> = Array_New<int>(4);
+    Array_Push<int>(&nums, 1);
+    Array_Push<int>(&nums, 2);
+    Array_Push<int>(&nums, 3);
+    let it = Array_Iter<int>(&nums);
+    let doubled = Iter_MapInt(&it, |x: int| -> int { return x * 2; });
+    return 0;
+}
+```
+
 ---
 
 ## Features
 
 | Feature | Status |
 |---------|--------|
-| **Types** | Primitives, pointers, slices, tuples, structs, enums, unions |
+| **Types** | Primitives, pointers, slices, tuples `(T,U)` + `.0`/`.1`, structs, enums, unions |
 | **Generics** | Generic functions (monomorphization) |
 | **Algebraic Enums** | Enums with data (`Result`, `Option`) |
 | **Pattern Matching** | `match` with guards |
 | **Methods** | `extend` blocks for struct methods |
 | **Interfaces** | `interface` + `extend` for trait-like behavior |
-| **Error Handling** | `Result<T,E>`, `Option<T>`, and the `?` operator |
+| **Error Handling** | `Result`/`Option`, `?`, `Expect`/`UnwrapOr`/`Or` helpers |
-| **Standard Library** | `Io`, `Array`, `String`, `Map`, `Fs`, `Mem`, `Set`, `Path`, `Math`, `Task`, `Channel`, `Sync`, `Os`, `Time`, `Process` |
+| **Closures** | Capture-less + capturing; **multi-instance** fat pointers (`BuxFn`) |
+| **Function pointers** | `func(T) -> R` as fat values; named funcs via adapters |
+| **Standard Library** | `Io`, `Array`, `String`, `Map`, `Set`, `Iter` (map/filter/fold), `Fs`, `Mem`, `Path`, `Math`, `Task`, `Channel`, `Sync`, `Os`, `Time`, `Process`, `Test`, … |
 | **Backend** | LIR → C transpiler (clean 3-address code, then gcc/clang) |
-| **Strings** | Raw multi-line backtick strings (`...`), C-string interop |
+| **Strings** | Raw multi-line backticks, `f"..."` interp (bootstrap), `ReplaceAll` / `IsBlank` / `Repeat` |
 | **Gradual Ownership** | `@[Checked]` + `@[Release]` + `@[Shared]` + `borrow &mut` / `borrow &` |
 | **Drop Trait** | Auto-drop for `@[Drop]` types (Array, Map, user-defined structs) |
 | **Green Threads** | M:N scheduler (ucontext + SIGVTALRM), work-stealing queues |
@@ -210,7 +245,8 @@ func Main() -> int {
 | **Trait Bounds** | `func Max<T: Comparable>(a: T, b: T) -> T` |
 | **Package Manager** | `bux add`, `bux install`, `bux.lock`, path + git deps |
 | **Cross-Compilation** | `--target <triple>` via clang (e.g. `aarch64-linux-gnu`) |
-| **Tooling** | `bux new`, `bux build`, `bux run`, `bux test`, `bux check` |
+| **Diagnostics** | Rust-style snippets, multi-char underlines, `= help:` hints |
+| **Tooling** | `bux new/build/run/test/check/fmt`, LSP (`tools/lsp_server.nim` + `buxc check`) |
 
 ---
 
@@ -255,12 +291,34 @@ bux/
 
 ---
 
+## Documentation
+
+| Doc | Description |
+|-----|-------------|
+| [`docs/LanguageRef.md`](docs/LanguageRef.md) | Language reference |
+| [`docs/Stdlib.md`](docs/Stdlib.md) | Standard library API |
+| [`docs/BuildAndTest.md`](docs/BuildAndTest.md) | Build, test, and tooling |
+| [`docs/QUALITY_PLAN.md`](docs/QUALITY_PLAN.md) | Roadmap toward a “good” v1.0 |
+| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Feature status (constructs) |
+| [`PLAN.md`](PLAN.md) | Long-form phase plan |
+
+---
+
 ## Build & Test
 
 ```bash
 # Build bootstrap compiler (Nim → C)
 make build
 
+# Run all example programs
+make test-examples
+
+# Golden diagnostic tests (Rust-style error format)
+make test-errors
+
+# Full unit + example suite
+make test
+
 # Build self-hosted compiler (Bux → C → native)
 make selfhost
 

docs/BuildAndTest.md

@@ -129,12 +129,20 @@ Use `--target <triple>` to cross-compile for a different platform. Bux generates
 
 ## Running Tests
 
+### Example suite
+```bash
+make test-examples   # all examples/ programs (40+)
+make test-errors     # golden Rust-style diagnostic output
+```
+
 ### Compiler Tests
 ```bash
 make test
 ```
 
 This runs:
+- Example suite (`test-examples`)
+- Error diagnostic goldens (`test-errors`)
 - Lexer unit tests
 - Parser unit tests
 - Semantic analysis unit tests

docs/QUALITY_PLAN.md

@@ -1,7 +1,7 @@
 # Bux — План към „добър“ език (v0.5 → v1.0)
 
-> **Дата:** 2026-07-15  
+> **Дата:** 2026-07-15 (обновено вечерта)  
-> **Текущо:** v0.5.0 — selfhost loop, gradual ownership, green threads, 26+ examples ✅  
+> **Текущо:** v0.5.x — selfhost loop, gradual ownership, green threads, **40+ examples** ✅  
 > **Цел:** Език, с който се пишат реални проекти комфортно, безопасно (по избор) и с надежден toolchain.
 
 ---
@@ -12,14 +12,14 @@
 |------|-----------|--------|
 | Frontend (lex/parse) | Пълен Pratt parser, recovery | ★★★★☆ |
 | Sema / generics | Monomorphization, trait bounds basic | ★★★★☆ |
-| HIR → C | Работи; tuples/func-ptr half-baked в bootstrap | ★★★☆☆ |
+| HIR → C | Tuples + fat `func` ABI в bootstrap **и** selfhost | ★★★★☆ |
-| Selfhost (`src/`) | ~12k LOC, binary-identical loop | ★★★★★ |
+| Selfhost (`src/`) | ~12k LOC, binary-identical loop, closures+tuples | ★★★★★ |
 | Gradual ownership | `@[Checked]`, `&`/`&mut`, move, Drop | ★★★☆☆ (basic) |
 | Concurrency | M:N tasks + channels + async | ★★★★☆ |
-| Stdlib | 25+ модула, но колекциите са минимални | ★★★☆☆ |
+| Stdlib | Array/Map/Set/String/Iter HOF разширени | ★★★★☆ |
-| Tooling | `new/build/run/test/fmt`, LSP prototype, VSCode | ★★☆☆☆ |
+| Tooling | `test-errors`, LSP diagnostics via `buxc check` | ★★★☆☆ |
 | Ecosystem / registry | path+git deps; няма централен registry | ★☆☆☆☆ |
-| Документация | Има, но drift (PLAN vs README версии) | ★★★☆☆ |
+| Документация | README + QUALITY_PLAN синхронизирани (2026-07-15) | ★★★★☆ |
 
 **Силна ниша:** gradual ownership (C-скорост на писане + opt-in Rust-safety).  
 **Слабо място:** ergonomics на stdlib + maturity на tooling + пълнота на borrow checker.
@@ -40,7 +40,7 @@
 
 ## Фази
 
-### A — Ergonomics & Stdlib (P0, сега) 🔄
+### A — Ergonomics & Stdlib (P0) ✅ (core done)
 
 | # | Задача | Защо | Статус |
 |---|--------|------|--------|
@@ -57,10 +57,11 @@
 |---|--------|------|--------|
 | B.1 | Proper tuple types в C backend | `(T,U)` → `Tuple_T_U` struct + `.0`/`.1` | ✅ bootstrap + selfhost |
 | B.2 | Function pointer types | `func(T)->U` fat ABI | ✅ bootstrap + selfhost |
-| B.3 | Match expression до край в C (не `return "0"`) | Expression-context match |
+| B.3 | Match expression до край в C (не `return "0"`) | Expression-context match | ⏳ |
-| B.4 | Closures: multi-instance + loop/return в body | Реални higher-order callbacks |
+| B.4 | Closures multi-instance | Fat `BuxFn` + heap env | ✅ bootstrap + selfhost |
+| B.4b | Closures: loop/return edge cases in body | По-сложни body control-flow | ⏳ |
 | B.5 | По-добри diagnostics (snippet + hint) | DX #1 за нови потребители | ✅ |
-| B.6 | Bootstrap ↔ selfhost feature parity | Operator overloading, string interp и в selfhost |
+| B.6 | Bootstrap ↔ selfhost feature parity | Tuples/closures done; string interp / ops still bootstrap-heavy | 🔄 |
 
 ### C — Gradual Ownership 2.0 (P1)
 

docs/ROADMAP.md

@@ -1,6 +1,7 @@
 # Bux Language Roadmap — New Constructs
 
-> **Updated:** 2026-06-09 | **Status:** In Progress
+> **Updated:** 2026-07-15 | **Status:** In Progress  
+> Recent: multi-instance closures (fat `BuxFn`), tuples in selfhost, Iter map/filter/fold, Rust-style diagnostics.
 
 This document tracks planned language constructs beyond Phase 8 strategy.