docs: update README and PLAN for v0.5.0

- README: add @[Release], green threads, drop trait, --release flag
- README: fix Task_Join → Task_Wait, update project structure
- README: add make selfhost-loop to build instructions
- PLAN: mark selfhost loop, borrow checker, release mode as done
- PLAN: update milestones summary

PLAN.md

@@ -652,36 +652,37 @@ bux/
 | Selfhost fix | ✅ | Build via `build/selfhost/` (project wrapper) |
 | Push to GitHub | ✅ | `ac969b3` — v0.3.0 restructure |
 
-### 10.1 — Selfhost Loop 🔄 (v0.4.0 target)
+### 10.1 — Selfhost Loop ✅ (v0.5.0 target)
 
 **Goal:** `buxc2` can compile itself producing a binary-identical `buxc3`.
 
 ```
-buxc (Nim) → src/*.bux → buxc2 ✅ (already works)
+buxc (Nim) → src/*.bux → buxc2 ✅
-buxc2       → src/*.bux → buxc3 🔄 (needs verification)
+buxc2       → src/*.bux → buxc3 ✅
-buxc2 == buxc3            🔄 (deterministic codegen)
+buxc2 == buxc3            ✅ (binary-identical)
 ```
 
 | Task | Status | Details |
 |------|--------|---------|
-| `10.1.1` Verify buxc2 can build src/ | 🔄 | Run `buxc2 build` on the selfhost project |
+| `10.1.1` Verify buxc2 can build src/ | ✅ | `buxc2 build` works on selfhost project |
-| `10.1.2` Deterministic C codegen | ⏳ | Remove timestamps, random IDs, non-deterministic ordering |
+| `10.1.2` Deterministic C codegen | ✅ | C output identical on every iteration |
-| `10.1.3` Binary-identical loop | ⏳ | `make selfhost-loop` — 2-pass bootstrap verification |
+| `10.1.3` Binary-identical loop | ✅ | `make selfhost-loop` passes (C + ELF parity) |
-| `10.1.4` Remove hardcoded paths | ⏳ | No `/home/ziko/...` paths in cli.bux |
+| `10.1.4` Remove hardcoded paths | ✅ | Paths resolved via `bux_getcwd()` / `bux_path_join()` |
 | `10.1.5` Selfhost test in CI | ⏳ | Add to `make test` |
 
-### 10.2 — Gradual Ownership 🔄 (v0.5.0 target) ⭐ Killer Feature
+### 10.2 — Gradual Ownership ✅ (v0.5.0 target) ⭐ Killer Feature
 
-**Goal:** `@[Checked]` functions get full borrow checking. Without this, Bux is "C with modern syntax."
+**Goal:** `@[Checked]` functions get full borrow checking. `@[Release]` disables checks for zero-cost hot paths.
 
 | Task | Status | Details |
 |------|--------|---------|
-| `10.2.1` `@[Checked]` attribute gate | ⏳ | Enable/disable borrow checker per function |
+| `10.2.1` `@[Checked]` attribute gate | ✅ | Enable/disable borrow checker per function |
-| `10.2.2` `&T` shared reference check | ⏳ | No mutation through shared refs |
+| `10.2.2` `&T` shared reference check | ✅ | No mutation through shared refs |
-| `10.2.3` `&mut T` exclusive mutable check | ⏳ | No aliasing of mutable refs |
+| `10.2.3` `&mut T` exclusive mutable check | ✅ | No aliasing of mutable refs |
-| `10.2.4` Bounds checking on slices | ⏳ | Buffer overflow prevention |
+| `10.2.4` Bounds checking on slices | ✅ | `Slice_Get` / `Array_Get` with `bux_bounds_check` |
-| `10.2.5` Lifetime elision (simple rules) | ⏳ | 80% of cases without annotations |
+| `10.2.5` `@[Release]` zero-cost mode | ✅ | Disables borrow + bounds checks, passes `-O3 -flto` |
-| `10.2.6` Explicit lifetimes `'a` | ⏳ | Only for complex cases |
+| `10.2.6` Lifetime elision (simple rules) | ⏳ | 80% of cases without annotations |
+| `10.2.7` Explicit lifetimes `'a` | ⏳ | Only for complex cases |
 
 ### 10.3 — Compiler Architecture Upgrade (v0.6.0 target)
 
@@ -854,11 +855,12 @@ func Main() -> int {
 | **M8** | 8-9 | ✅ | **Borrow checker**, **CTFE**, **Package manager** working |
 | **M9** | 8.5 | ✅ | **Trait bounds** (`<T: Comparable>`) — semantic checking implemented |
 | **M10** | 10 | ✅ | **LIR backend** replaces HIR→C; 26/26 examples pass; selfhost builds |
-| **M11** | 11 | 🔄 | Selfhost loop: `buxc2` compiles itself → binary-identical `buxc3` |
+| **M11** | 11 | ✅ | **Selfhost loop**: `buxc2` compiles itself → binary-identical `buxc3` |
-| **M12** | 11.3 | ⏳ | `@[Checked]` borrow checker works on real code |
+| **M12** | 11.3 | ✅ | `@[Checked]` borrow checker works on real code |
-| **M13** | 11.4 | ⏳ | `bux test`, `bux fmt`, `bux doc` shipped |
+| **M13** | 11.4 | ✅ | `@[Release]` zero-cost mode; Rust-style error snippets |
-| **M14** | 11.5 | ⏳ | Native x86-64 backend (no C transpiler) |
+| **M14** | 8.3 | ✅ | **Green threads** — M:N scheduler with channels |
-| **M15** | 8.7 | ⏳ | `@[Release]` mode — zero-cost abstractions; C-speed benchmarks vs Nim/Crystal |
+| **M15** | 11.5 | ⏳ | Native x86-64 backend (no C transpiler) |
+| **M16** | 11.4 | ⏳ | `bux test`, `bux fmt`, `bux doc` shipped |
 
 ---
 

README.md

@@ -2,11 +2,11 @@
 
 ![Bux Language](bux-lang-01.jpeg)
 
-> **Status:** v0.4.0 — Bootstrap compiler (`buxc`, Nim) and self-hosted compiler (`buxc2`, Bux) both compile `.bux` → C → native binary.
+> **Status:** v0.5.0 — Bootstrap compiler (`buxc`, Nim) and self-hosted compiler (`buxc2`, Bux) both compile `.bux` → C → native binary.
-> **Selfhost loop:** `buxc2` can compile itself — deterministic C codegen verified.
+> **Selfhost loop:** `buxc2` compiles itself → binary-identical `buxc3` ✅ Deterministic C codegen + ELF verified.
-> **LIR backend** produces clean 3-address C code. All 26 examples pass.
+> **Gradual Ownership:** `@[Checked]` borrow checker, `@[Release]` zero-cost mode, `borrow &mut` expressions.
-> **Gradual Ownership:** `@[Checked]` borrow checker, `borrow &mut` expressions, `@[Shared]` attribute.
+> **Green Threads:** M:N scheduler with channels (Go-style goroutines without GC).
-> **Apps tested:** compiler successfully parses all 3 real-world apps (`apps/boko-framework`, `apps/jwt-pitbul`, `apps/nexus`) — no hangs, no crashes.
+> **All 26 examples pass.** Compiler successfully parses all 3 real-world apps (`apps/boko-framework`, `apps/jwt-pitbul`, `apps/nexus`).
 
 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.
 
@@ -25,6 +25,9 @@ cd hello
 # Build and run
 bux run
 
+# Build optimized release binary
+bux build --release
+
 # Cross-compile for ARM Linux (requires clang)
 bux build --target aarch64-linux-gnu
 ```
@@ -134,7 +137,7 @@ func Main() -> int {
 ### Channels (Producer/Consumer)
 ```bux
 import Std::Io::{PrintLine, PrintInt};
-import Std::Task::{Task_Join, TaskHandle};
+import Std::Task::{Task_Wait, TaskHandle};
 import Std::Channel::{Channel, Channel_New, Channel_SendInt, Channel_RecvInt, Channel_Close};
 
 func Producer(chPtr: *Channel<int>) {
@@ -164,8 +167,8 @@ func Main() -> int {
     let ch: Channel<int> = Channel_New<int>(3);
     let p: *void = spawn Producer(&ch);
     let c: *void = spawn Consumer(&ch);
-    Task_Join(TaskHandle { handle: p });
+    Task_Wait(TaskHandle { handle: p });
-    Task_Join(TaskHandle { handle: c });
+    Task_Wait(TaskHandle { handle: c });
     return 0;
 }
 ```
@@ -198,7 +201,9 @@ func Main() -> int {
 | **Standard Library** | `Io`, `Array`, `String`, `Map`, `Fs`, `Mem`, `Set`, `Path`, `Math`, `Task`, `Channel`, `Sync`, `Os`, `Time`, `Process` |
 | **Backend** | LIR → C transpiler (clean 3-address code, then gcc/clang) |
 | **Strings** | Raw multi-line backtick strings (`...`), C-string interop |
-| **Gradual Ownership** | `@[Checked]` + `@[Shared]` + `borrow &mut` / `borrow &` expressions |
+| **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 |
 | **Async/Await** | `async func`, `spawn`, `.await` with stackful coroutines |
 | **Concurrency** | `Task`/`Channel`/`Sync` (pthread-based), `bux_async_yield`/`spawn` |
 | **CTFE** | `const func` — compile-time function execution |
@@ -213,24 +218,38 @@ func Main() -> int {
 
 ```
 bux/
-├── compiler/         # Compiler source code
+├── src/              # 🎯 Self-hosting compiler source (Bux)
-│   ├── bootstrap/    # Bootstrap compiler (Nim)
+│   ├── main.bux      # Entry point
-│   ├── selfhost/     # Self-hosting compiler source (Bux)
+│   ├── lexer.bux     # Tokenizer
-│   └── tests/        # Compiler unit tests (Nim)
+│   ├── parser.bux    # Pratt parser
-├── library/          # Standard library
+│   ├── ast.bux       # AST node types
-│   ├── std/          # Standard library modules (.bux)
+│   ├── sema.bux      # Type checker
-│   │   ├── Io.bux, String.bux, Array.bux, Map.bux
+│   ├── hir_lower.bux # AST → HIR lowering
-│   │   ├── Fs.bux, Mem.bux, Set.bux
+│   ├── c_backend.bux # HIR → C code generator
-│   │   ├── Path.bux, Math.bux
+│   └── cli.bux       # CLI driver
-│   │   └── Task.bux, Channel.bux
+├── bootstrap/        # 🔧 Bootstrap compiler (Nim)
-│   └── runtime/      # C runtime files (runtime.c, io.c)
+│   ├── main.nim      # Entry point
-├── tests/            # Language integration tests
+│   ├── cli.nim       # CLI commands + build driver
+│   └── ...           # (mirrors src/ structure)
+├── lib/              # 📦 Standard library (23 modules)
+│   ├── Io.bux        # Print, ReadFile, WriteFile
+│   ├── String.bux    # Full string API
+│   ├── Array.bux     # Generic Array<T>
+│   ├── Map.bux       # Generic Map<K,V> + StringMap
+│   ├── Set.bux       # Generic Set<T>
+│   ├── Task.bux      # Green threads (spawn/await)
+│   ├── Channel.bux   # Producer/consumer channels
+│   ├── Drop.bux      # Drop trait interface
+│   └── ...           # Math, Fs, Path, Sync, Result, ...
+├── rt/               # ⚙️ C runtime
+│   ├── runtime.c     # Memory, scheduler, channels
+│   └── io.c          # File I/O wrappers
+├── tests/            # 🧪 Unit tests (Nim)
 ├── examples/         # Example programs
-├── tools/            # Additional tooling
+├── apps/             # Real-world applications
 ├── docs/             # Documentation
-├── buxs/             # Windows-compatible project root
 ├── README.md
-├── PLAN.md           # Roadmap to self-hosting
+├── PLAN.md           # Roadmap to v1.0.0
 └── Makefile
 ```
 
@@ -251,6 +270,9 @@ make test
 # Run example programs
 make test-examples
 
+# Verify selfhost binary parity (buxc2 → buxc3, identical)
+make selfhost-loop
+
 # Clean build artifacts
 make clean
 ```