VC: update docs

content/docs/components/classes.mdx

@@ -4,21 +4,21 @@ description: Unified data and behavior with Java-style organization and Rust-pow
 icon: Shapes
 ---
 
-Classes in Mist bridge the gap between Java's organizational structure and Rust's performance. They group fields, constructors, and methods within a single cohesive block, using `fn` for methods and `*self` for the instance parameter.
+Classes in Mist bridge the gap between Java's organizational structure and Rust's performance. They group fields, constructors, and methods within a single cohesive block, using C-style method signatures with `&self` for the instance parameter.
 
 ## Basic Syntax
 
-A class groups fields and methods together. Fields use semicolons and the `name Type` convention. Methods use `fn` and take `*self` as the first parameter for shared access.
+A class groups fields and methods together. Fields use semicolons and the `Type name` convention. Methods use C-style syntax with `&self` as the first parameter for shared access.
 
 ```mist
 pub class Logger {
-    prefix String;
+    String prefix;
 
-    pub fn info(*self, message *str) {
+    pub void info(&self, message str&) {
         self.log(LogLevel::Info, message);
     }
 
-    fn log(*self, level LogLevel, message *str) {
+    void log(&self, LogLevel level, message str&) {
         println!("{level} {} {}", self.prefix, message);
     }
 }
@@ -37,58 +37,71 @@ pub constructor() {
 Constructors can take parameters:
 
 ```mist
-pub constructor(prefix String) {
+pub constructor(String prefix) {
     self.prefix = prefix;
 }
 ```
 
-## Instance Methods & `*self`
+## Instance Methods & `&self`
 
-Methods use `*self` (shared reference) or `*mut self` (mutable reference) as the first parameter. The return type is placed after the parameter list.
+Methods use `&self` (shared reference) or `&mut self` (mutable reference) as the first parameter.
 
 ```mist
-pub fn warning(*self, message *str) {
+pub void warning(&self, message str&) {
     self.log(LogLevel::Warning, message);
 }
 
-pub fn reset(*mut self) {
+pub void reset(&mut self) {
     self.prefix = String::new();
 }
 ```
 
 ## Inheritance
 
-Classes support single inheritance with the `:` syntax. Use `super -> Super::new()` in the constructor to call the parent constructor. Override methods with `override` or `override(Parent)`.
+Classes support single inheritance with the `:` syntax. Use `super = Super::new()` in the constructor to call the parent constructor. Override methods by placing `override(Parent)` after the parameter list.
 
 ```mist
 pub class Animal {
-    pub name String;
+    pub String name;
 
     constructor() {
         self.name = "Rex".to_string();
     }
 
-    pub fn speak(*self) {
+    pub String speak(&self) {
-        println!("Unknown");
+        "Unknown".to_string()
-    }
-
-    pub fn legs(*self) {
-        println!("Unknown");
     }
 }
 
 pub class Dog : Animal {
     constructor() {
-        super -> Super::new();
+        super = Super::new();
     }
 
-    pub override fn speak(*self) {
+    pub String speak(&self) override(Animal) {
-        println!("Woof!");
+        "Woof!".to_string()
+    }
+}
+```
+
+## Trait Implementations
+
+Traits can be implemented directly inside a class body:
+
+```mist
+pub class Dog : Animal {
+    constructor() {
+        self.name = name;
     }
 
-    // Explicit override is useful for super inheritance
+    pub String speak(&self) override(Animal) {
-    pub override(Animal) fn legs(*self) {
+        "Woof!".to_string()
-        println!("4 legs");
+    }
+
+    impl std::fmt::Display {
+        Result<(), std::fmt::Error> fmt(&self, std::fmt::Formatter<'_> mut& f) {
+            write!(f, "🐾 {}", self.name)
+        }
     }
 }
 ```
@@ -99,37 +112,24 @@ Classes support generic type parameters:
 
 ```mist
 pub class Container<T> {
-    pub value T;
+    T value;
 
-    constructor(val T) {
+    constructor(T val) {
         self.value = val;
     }
 
-    pub fn get(*self) *T {
+    pub &T get(&self) {
         &self.value
     }
 }
 ```
 
-## Allocations
-In classes, it's very important to initialize heap allocated fields in `constructor` using `path -> expr`, here is the most common example:
-```mist
-pub class Dog : Animal {
-    pub heap_alloc Box<i32>;
-
-    constructor() {
-        super -> Super::new();
-        self.heap_alloc -> Box::new(69);
-    }
-}
-```
-This outputs `std::ptr::write` which is a force write to memory without dropping what "exists", and it's commonly used in uninitialized memory, such as uninitialized dynamic fields.
-
 ## Key Characteristics
 
 - **Unified Scope**: Data and behavior live in one class block.
-- **`fn` Methods**: Methods use the `fn` keyword, consistent with free functions.
+- **C-Style Methods**: Return type before name — no `fn` keyword.
-- **`*self` Parameter**: The self reference is explicit and uses prefix `*` syntax.
+- **`&self` Parameter**: The self reference is explicit and uses `&` syntax.
-- **Inheritance**: Single inheritance with `override` for polymorphic dispatch.
+- **Inheritance**: Single inheritance with `override(Parent)` for polymorphic dispatch.
 - **Encapsulation**: Visibility modifiers (`pub`) control API exposure.
+- **Inline Impl**: Traits can be implemented directly within the class body.
 - **Zero-Cost Classes**: Under the hood, Mist desugars these into idiomatic Rust structs and implementation blocks.

content/docs/components/enums.mdx

@@ -1,14 +1,14 @@
 ---
 title: Enums
-description: Defining algebraic data types with Mist's data-first convention.
+description: Defining algebraic data types with Mist's type-first convention.
 icon: Layers
 ---
 
-Enums in Mist serve as powerful algebraic data types (ADTs), maintaining the exact behavior and safety of Rust enums while using square brackets for tuple variant types and `name Type` for struct-like fields.
+Enums in Mist serve as powerful algebraic data types (ADTs), maintaining the exact behavior and safety of Rust enums while using parentheses for tuple variants and `Type name` for struct-like fields.
 
 ## Basic Syntax
 
-An enum can contain unit variants, tuple variants (with types in square brackets), or struct-like variants.
+An enum can contain unit variants, tuple variants (with types in parentheses), or struct-like variants.
 
 ```mist
 pub enum TaskState {
@@ -16,8 +16,8 @@ pub enum TaskState {
     InProgress,
     Completed,
     Failed {
-        reason String,
+        String reason,
-        code i32,
+        i32 code,
     },
 }
 ```
@@ -29,57 +29,59 @@ Mist supports all standard variant shapes:
 ```mist
 enum OptionInt {
     None,                         // Unit
-    Some[i32],                    // Tuple (square brackets)
+    Some(i32),                    // Tuple (parentheses)
 }
 
 enum Shape {
-    Circle { radius i32 },        // Struct-like
+    Circle { i32 radius },        // Struct-like
-    Rect { w i32, h i32 },
+    Rect { i32 w, i32 h },
 }
 ```
 
 ### Instantiation & Matching
 
-Tuple variants are created with parentheses and matched with brackets:
+Tuple variants are created and matched with parentheses:
 
 ```mist
 let x = OptionInt::Some(42);
 
-match (x) {
+match x {
     OptionInt::None => { println!("none"); }
-    OptionInt::Some[v] => { println!("{}", v); }
+    OptionInt::Some(v) => { println!("{}", v); }
 }
 ```
 
 Struct variants use brace notation:
 
 ```mist
-let c = Shape::Circle { radius: 5 };
+let c = Shape::Circle {
+    radius: 5,
+};
 
-match (c) {
+match c {
     Shape::Circle { radius } => { println!("{}", radius); }
     Shape::Rect { .. } => { /* ignore */ }
 }
 ```
 
-## Generics & Lifetimes
+## Generics
 
-Enums declare generics and lifetimes in angle brackets after the name. Reference types use the `*` prefix.
+Enums declare generics and lifetimes in angle brackets after the name.
 
 ```mist
 pub enum Validation<'a, T> {
     Valid(T),
     Invalid {
-        message *'a str,
+        &'a str message,
-        error_id u32,
+        u32 error_id,
     },
 }
 ```
 
 ## Key Characteristics
 
-- **Consistent Declaration**: Struct-like variants use the `name Type` order, consistent with Mist structs.
+- **Consistent Declaration**: Struct-like variants use `Type name` order, consistent with Mist structs.
-- **Square Bracket Tuples**: Tuple variant types use `[]` brackets, distinct from function calls.
+- **Parentheses Tuples**: Tuple variants use `()` syntax, consistent with Rust.
 - **Rust-Native ADTs**: Enums compile directly to Rust enums, allowing exhaustive pattern matching and zero-cost abstraction.
 - **Shared Visibility**: The `pub` modifier at the enum level exports all variants.
 - **Comma-Separated Members**: Fields within struct-like variants are separated by commas.

content/docs/components/functions.mdx

@@ -4,67 +4,78 @@ description: Defining execution blocks with C-style ergonomics and Rust-powered
 icon: SquareFunction
 ---
 
-Functions are the primary unit of execution in Mist, declared with the `fn` keyword. Parameters follow the `name Type` convention and the return type is placed after the parameter list.
+Functions are the primary unit of execution in Mist, using C-style syntax with the return type before the name. The last expression in a block is implicitly returned.
 
 ## Basic Syntax
 
-A standard function begins with `fn`, followed by its name, parameters, and an optional return type. The last expression in a block is implicitly returned.
+Functions place the return type before the name, followed by parameters in parentheses.
 
 ```mist
-fn add(a i32, b i32) i32 {
+void greet() {
-    a + b
+    println!("Hello!");
 }
 
-fn greet() {
+i32 add(i32 a, i32 b) {
-    println!("Hello!");
+    a + b
 }
 ```
 
-## Visibility & Exports
+## Visibility & Modules
 
-Functions are private to their module by default. The `pub` modifier exports the function for cross-module access.
+Functions use `pub` for public visibility. Files declare a module with `pub module name;`.
 
 ```mist
-pub fn get_version() i32 {
+pub module utils;
+
+pub i32 get_version() {
     1
 }
 
-pub(crate) fn internal_use() i32 {
+pub void process() {
-    0
+    // ...
 }
 ```
 
 ## Mutable Parameters
 
-Use `mut` on a parameter to allow reassignment within the function body.
+Use `mut` after the type to allow reassignment within the function body.
 
 ```mist
-fn update_score(mut current_score i32, bonus i32) i32 {
+void update_score(i32 mut current_score, i32 bonus) {
     current_score = current_score + bonus;
-    current_score
 }
 ```
 
-## Generics & Lifetimes
+## Methods & `&self`
 
-Generics and lifetimes are declared in angle brackets after the function name. Lifetimes are placed before the `*` in reference types.
+Methods take `&self` (immutable) or `&mut self` (mutable) as the first parameter.
 
 ```mist
-fn choose_longer<'a>(s1 *'a str, s2 *'a str) *'a str {
+struct Counter {
-    if (s1.len() > s2.len()) { s1 } else { s2 }
+    i32 value,
+}
+
+impl Counter {
+    pub i32 get(&self) {
+        self.value
+    }
+
+    pub void increment(&mut self) {
+        self.value += 1;
+    }
 }
 ```
 
 ## Closures
 
-Closures are anonymous functions defined with the `fn` keyword followed by parameters, an optional return type, and a body or expression.
+Closures are anonymous functions defined with arrow syntax:
 
 ```mist
-let add = fn(a, b) -> a + b;
+let add = (a, b) => a + b;
 add(2, 3);
 
 // With a block body
-let greet = fn(name *str) {
+let greet = (name str&) => {
     println!("Hello {}", name);
 };
 ```
@@ -75,15 +86,17 @@ Metadata is applied via the `#[attr]` syntax directly above the declaration.
 
 ```mist
 #[inline]
-pub fn is_active(id u32) bool {
+pub i32 clamp(i32 value, i32 min, i32 max) {
-    id > 0
+    if value < min { min }
+    else if value > max { max }
+    else { value }
 }
 ```
 
 ## Key Characteristics
 
-- **`fn` Keyword**: Every function starts with `fn`, making declarations instantly recognizable.
+- **C-Style Syntax**: Return type before name — no `fn` keyword.
 - **Implicit Returns**: The final expression in a block is automatically returned.
-- **Unified Abstraction**: Lifetimes and type constraints are declared in one location.
+- **`&self` / `&mut self`**: Explicit self parameter in method definitions.
-- **Closure Support**: Anonymous functions with optional return type annotations.
+- **Closure Support**: Arrow syntax `(params) => expr` for anonymous functions.
 - **Zero-Cost Mapping**: Every function maps directly to a Rust `fn`.

content/docs/components/modules-imports.mdx

@@ -6,9 +6,24 @@ icon: FolderTree
 
 Mist organizes code through a file-system based module system with explicit path imports.
 
-## The Module System
+## Module Declarations
 
-Each `.mist` file in `src/` corresponds to a module. and a `directory/package.mist` is a package like mod.rs, packages don't need `package.mist` to be functional, as long as a `.mist` file exists it will map it to pacakge_name::file_name.
+Each `.mist` file declares itself as a module with `pub module name;` at the top. A `package.mist` file acts like `mod.rs` — it is the entry point for its directory.
+
+```mist
+// src/utils/helper.mist
+pub module helper;
+
+pub void greet() {
+    println!("Hello!");
+}
+```
+
+```mist
+// src/utils/package.mist
+pub module utils;
+// This module exports submodules and items
+```
 
 ## Imports
 
@@ -51,6 +66,7 @@ A typical Mist project looks like this:
 ```
 my-project/
 ├── Cargo.toml
+├── Mist.toml
 ├── src/
 │   ├── main.mist
 │   ├── my_api/

content/docs/components/pointers-references.mdx

@@ -1,29 +1,29 @@
 ---
 title: Pointers & References
-description: Explicit memory access with prefix pointer syntax and Rust-native safety.
+description: Explicit memory access with postfix reference syntax and Rust-native safety.
 icon: MousePointer2
 ---
 
-Mist uses a prefix `*` syntax for reference types. While the symbols look like C-style pointers, they adhere strictly to Rust's ownership and borrowing rules.
+Mist uses a postfix `&` syntax for reference types. While familiar from C++, these references adhere strictly to Rust's ownership and borrowing rules.
 
 ## Basic Syntax
 
-Reference types are written with `*` before the type. Use `*mut` for mutable references. The `&` and `&mut` operators create references from values.
+Reference types are written with `&` after the type. Use `mut&` for mutable references. The `&` and `&mut` operators create references from values.
 
 ```mist
-let x i32 = 42;
+i32 x = 42;
-let r *i32 = &x;
+i32& r = &x;
 
 let mut y = 42;
-let r *mut i32 = &mut y;
+i32 mut& r = &mut y;
 *r = 100;
 ```
 
 In function parameters:
 
 ```mist
-fn increment(value *mut i32, limit *i32) {
+void increment(i32 mut& value, i32& limit) {
-    if (*value < *limit) {
+    if *value < *limit {
         *value = *value + 1;
     }
 }
@@ -31,30 +31,37 @@ fn increment(value *mut i32, limit *i32) {
 
 ## Lifetimes
 
-Lifetimes are placed between `*` and the type, reading as "pointer with lifetime to type":
+Lifetimes are placed before the type in the `&` suffix:
 
 ```mist
 pub struct Inspector<'a> {
-    pub target *'a str,
+    &'a str target,
-    pub counter *'a mut u32,
+    &'a mut u32 counter,
 }
 ```
 
-## Allocations
+## In Classes
-In classes, it's very important to initialize heap allocated fields in `constructor` using `path -> expr`, here is the most common example:
+
+Methods use `&self` for immutable access and `&mut self` for mutable access:
+
 ```mist
-pub class Dog : Animal {
+pub class Logger {
-    constructor() {
+    String prefix;
-        super -> Super::new();
+
+    pub void info(&self, message str&) {
+        println!("{}", message);
+    }
+
+    pub void reset(&mut self) {
+        self.prefix = String::new();
     }
 }
 ```
-This outputs `std::ptr::write` which is a force write to memory without dropping what "exists", and it's commonly used in uninitialized memory, such as uninitialized dynamic fields.
 
 ## Key Characteristics
 
-- **Prefix Pointer Syntax**: `*Type` for shared references, `*mut Type` for mutable references.
+- **Postfix Reference Syntax**: `T&` for shared references, `T mut&` for mutable references.
-- **Explicit Intent**: The `*mut` syntax clearly distinguishes read-only from writable references, mapping 1:1 to Rust's `&` and `&mut`.
+- **Explicit Intent**: The `mut&` syntax clearly distinguishes read-only from writable references.
-- **Visual Consistency**: Lifetimes (`'a`) are placed before the type in `*'a Type`, keeping the declaration flow left-to-right.
+- **Visual Consistency**: Lifetimes (`'a`) are placed before the type in `&'a T`.
-- **Safety Guaranteed**: Despite the "pointer" appearance, the Mist compiler enforces Rust's borrow checker.
+- **Safety Guaranteed**: The Mist compiler enforces Rust's borrow checker.
-- **Zero Overhead**: Mist pointers compile to identical machine code as Rust references.
+- **Zero Overhead**: Mist references compile to identical machine code as Rust references.

content/docs/components/structs.mdx

@@ -1,20 +1,20 @@
 ---
 title: Structs
-description: Data modeling with Mist's name-first field convention.
+description: Data modeling with Mist's type-first field convention.
 icon: Form
 ---
 
-Structs in Mist follow the same structural logic as Rust, with fields using the language-wide `name Type` convention and comma-separated grouping.
+Structs in Mist follow the same structural logic as Rust, with fields using the language-wide `Type name` convention and comma-separated grouping.
 
 ## Basic Syntax
 
-A struct is defined by its name followed by a block of fields. Each field places the identifier before the type.
+A struct is defined by its name followed by a block of fields. Each field places the type before the identifier.
 
 ```mist
 pub struct Task {
-    pub name String,
+    pub String name,
-    pub state TaskState,
+    pub TaskState state,
-    pub executions i32,
+    pub i32 executions,
 }
 ```
 
@@ -24,14 +24,14 @@ Use the `pub` modifier to make the struct or its individual fields accessible fr
 
 ```mist
 pub struct NetworkNode {
-    pub id u32,
+    pub u32 id,
-    address *str,
+    str& address,
 }
 ```
 
 ## Instantiation
 
-Structs are instantiated using the standard brace syntax.
+Structs are instantiated using standard brace syntax.
 
 ```mist
 let task = Task {
@@ -41,29 +41,44 @@ let task = Task {
 };
 ```
 
+## Mutation
+
+Use `let mut` to allow field reassignment.
+
+```mist
+let mut p = Point {
+    x: 1,
+    y: 2,
+};
+p.x = 100;
+```
+
 ## Destructuring
 
 Struct patterns use `let` with the struct name and field bindings:
 
 ```mist
-let p = Point { x: 3, y: 4 };
+let p = Point {
+    x: 3,
+    y: 4,
+};
 let Point { x, y } = p;
 ```
 
-## Generics & Lifetimes
+## Generics
 
-Generics and lifetimes are declared in angle brackets after the struct name. Reference types use the `*` prefix.
+Generics and lifetimes are declared in angle brackets after the struct name.
 
 ```mist
 pub struct Buffer<'a, T> {
-    pub data *'a T,
+    &'a T data,
-    pub len usize,
+    usize len,
 }
 ```
 
 ## Key Characteristics
 
-- **Name-First Declaration**: Fields use `name Type` order, consistent with function parameters and variable declarations.
+- **Type-First Declaration**: Fields use `Type name` order, consistent with function parameters and variable declarations.
 - **Comma-Separated Members**: Fields are separated by commas, maintaining a clean delimiter style.
 - **Rust Compatibility**: Maps 1:1 to Rust structs, ensuring zero-cost abstraction and full ecosystem interoperability.
 - **Direct Visibility**: The `pub` modifier controls access at the struct and field level.

content/docs/components/traits.mdx

@@ -4,16 +4,16 @@ description: Defining shared behavior and contracts with Mist's signature ergono
 icon: Sparkles
 ---
 
-Traits in Mist define a set of methods that a type must implement, facilitating polymorphism and shared behavior. Method signatures use the `fn` keyword with `*self` for the instance parameter.
+Traits in Mist define a set of methods that a type must implement, facilitating polymorphism and shared behavior. Method signatures use C-style syntax with `&self` for the instance parameter.
 
 ## Defining a Trait
 
-A trait lists method signatures using `fn`, with `*self` as the instance parameter and the return type after the parameter list.
+A trait lists method signatures using return-type-first syntax, with `&self` as the instance parameter.
 
 ```mist
 pub trait Drawable {
-    fn draw(*self);
+    void draw(&self);
-    fn metadata(*self) *str;
+    str& metadata(&self);
 }
 ```
 
@@ -23,11 +23,11 @@ Use `impl Trait for Type` to provide implementations:
 
 ```mist
 impl Drawable for Task {
-    fn draw(*self) {
+    void draw(&self) {
         println!("Drawing task: {}", self.name);
     }
 
-    fn metadata(*self) *str {
+    str& metadata(&self) {
         self.name
     }
 }
@@ -39,9 +39,9 @@ Traits can provide default behavior for methods that implementing types may over
 
 ```mist
 pub trait Identifiable {
-    fn get_id(*self) u32;
+    u32 get_id(&self);
 
-    fn is_valid(*self) bool {
+    bool is_valid(&self) {
         self.get_id() > 0
     }
 }
@@ -53,18 +53,18 @@ A trait can require another trait using the colon `:` syntax:
 
 ```mist
 pub trait Speak {
-    fn speak(*self) String;
+    String speak(&self);
 }
 
 pub trait Greet : Speak {
-    fn greet(*self) String;
+    String greet(&self);
 }
 ```
 
 ## Key Characteristics
 
-- **`fn` Signatures**: Method signatures use `fn`, consistent with free functions.
+- **C-Style Signatures**: Return type before name — no `fn` keyword.
-- **Explicit Context**: Methods use `*self` as the first parameter, mapping directly to Rust's reference rules.
+- **Explicit Context**: Methods use `&self` as the first parameter, mapping directly to Rust's reference rules.
 - **Default Methods**: Traits can provide default implementations.
 - **Super-traits**: Colon syntax for expressing trait requirements.
 - **Static Dispatch**: By default, Mist traits leverage Rust's zero-cost generics and monomorphization.

content/docs/limitations.mdx

@@ -4,7 +4,7 @@ description: Understanding the Alpha state of Mist and our technical roadmap.
 icon: TriangleAlert
 ---
 
-Mist is currently in a **Volatile Alpha** stage. Our current priority is exploring **Syntax and Features**. We believe in stabilizing the developer experience and the "feel" of the language before locking in the deep architectural logic of the compiler.
+Mist is currently in a **Volatile Alpha** stage (latest: v0.3.7-alpha.0). Our current priority is exploring **Syntax and Features**. We believe in stabilizing the developer experience and the "feel" of the language before locking in the deep architectural logic of the compiler.
 
 The compiler, transpiler, and CLI are partially bootstrapped — written in Mist itself. This gives us real-world feedback on every language design decision.
 

content/docs/logic/control-flow.mdx

@@ -4,26 +4,23 @@ description: Directing execution with expression-based logic, pattern matching,
 icon: Split
 ---
 
-Control flow in Mist provides a bridge between C-style procedural logic and Rust's expression-oriented design. Blocks, if statements, while/for/loop loops, and match expressions all support statement bodies.
+Control flow in Mist provides a bridge between C-style procedural logic and Rust's expression-oriented design. Conditions do not require parentheses, and blocks support expression bodies.
 
 ## Conditionals
 
-The `if` statement evaluates a boolean expression:
+The `if` statement evaluates a boolean expression without parentheses:
 
 ```mist
-if (score > 50) {
+if score > 50 {
     println!("Pass");
-} else if (score == 50) {
+} else if score == 50 {
     println!("Borderline");
 } else {
     println!("Fail");
 }
 
-// Single-statement body (no braces needed)
-if (is_active) println!("Running");
-
 // Expression body (implicit return)
-let result = if (valid) { "ok" } else { "err" };
+let result = if valid { "ok" } else { "err" };
 ```
 
 ## Match
@@ -31,7 +28,7 @@ let result = if (valid) { "ok" } else { "err" };
 The `match` statement provides exhaustive pattern matching with support for multiple patterns per arm via `|`:
 
 ```mist
-match (task_state) {
+match task_state {
     TaskState::Pending => { println!("Queued"); }
     TaskState::Failed { reason, code } => {
         println!("Error {}: {}", code, reason);
@@ -49,9 +46,9 @@ Patterns support destructuring, or-patterns, and wildcards:
 let x = 2;
 let result;
 
-match (x) {
+match x {
     1 => { result = 10; }
-    2 => { result = 20; }
+    2 => result = 20,
     3 => { result = 30; }
     _ => panic!();
 }
@@ -66,33 +63,39 @@ An infinite loop construct:
 ```mist
 loop {
     println!("forever");
-    if (done) break;
+    if done { break; }
 }
 ```
 
 ### For-In Loop
 
-For loops iterate over an expression using the `pattern : expr` syntax:
+For loops iterate over an expression using `for pattern in expr` syntax:
 
 ```mist
-for (i : 0..4) {
+for i in 0 .. 4 {
     sum += i;
 }
 
 // With pattern destructuring
-for ([k, _] : pairs) {
+for (k, _) in pairs {
     keys += k;
 }
+
+// With range variable
+let r = 0 .. 5;
+for i in r {
+    count++;
+}
 ```
 
 ### While Loop
 
 ```mist
-while (count < 5) {
+while count < 5 {
     count++;
 }
 
-while (active) {
+while active {
     wait_for_event();
 }
 ```
@@ -105,7 +108,8 @@ while (active) {
 
 ## Key Characteristics
 
-- **Statement Bodies**: If, while, for, and loop branches can omit braces for single statements or expressions.
+- **No Parentheses**: Conditions in `if`, `while`, and `match` do not require parentheses.
-- **Implicit Returns**: Expression bodies (without `;`) implicitly return their value.
+- **Implicit Returns**: Expression bodies implicitly return their value.
 - **Pattern Integration**: Loops and match arms utilize Mist's pattern system for data destructuring.
 - **Multiple Patterns**: Match arms support `|` for matching multiple patterns.
+- **Expression `if`**: `if/else` blocks can be used as expressions.

content/docs/logic/expressions.mdx

@@ -12,7 +12,7 @@ Primary expressions are the starting point of any logic chain. These include lit
 
 ```mist
 let x = 42;
-let y = Math::PI;
+let pi = Math::PI;
 let coordinates = (10, 20, 30);
 ```
 
@@ -72,6 +72,8 @@ let content = fs::read_to_string(path)?;
 
 ### Range Operators
 
+Ranges use spaced `..` syntax:
+
 ```mist
 0 .. 10        // exclusive range (0 to 9)
 0 ..= 10       // inclusive range (0 to 10)
@@ -108,6 +110,17 @@ let is_equal = (x == y);
 let complex = (a + b) * (c / d);
 ```
 
+## Closures
+
+Closures use arrow syntax with optional type annotations:
+
+```mist
+let add = (a, b) => a + b;
+let greet = (name str&) => {
+    println!("Hello {}", name);
+};
+```
+
 ## Operator Table
 
 | Category       | Operators                                                        |
@@ -126,3 +139,4 @@ let complex = (a + b) * (c / d);
 - **Macro Integration**: Macros use `!` as a postfix operation.
 - **Type Casting**: `as Type` provides explicit type conversion at the expression level.
 - **Error Propagation**: The `?` operator enables early returns for `Result`/`Option` types.
+- **Arrow Closures**: `(params) => expr` for concise anonymous functions.

content/docs/logic/variables.mdx

@@ -4,15 +4,27 @@ description: Local state management with type inference and explicit mutability.
 icon: Variable
 ---
 
-Variables in Mist are declared with the `let` keyword. Like Rust, variables are immutable by default, and types are written after the name for scannability.
+Variables in Mist support two declaration styles: inferred typing with `let` and explicit type annotation. Like Rust, variables are immutable by default.
 
 ## Basic Declaration
 
-Variables use `let` for automatic type inference. The type annotation is optional — when omitted, the compiler infers the type from the value.
+Use `let` for automatic type inference:
 
 ```mist
 let x = 42;
 let greeting = "Hello Mist";
+let s = "hello, world!";
+```
+
+## Explicit Typing
+
+Type annotations are placed before the name:
+
+```mist
+i32 x = 42;
+bool is_active = true;
+str& name = "mist";
+f64 pi = 3.14;
 ```
 
 ## Mutability
@@ -24,14 +36,20 @@ let mut score = 0;
 score = 100;
 ```
 
-## Explicit Typing
+Or with explicit typing:
-
-Type annotations are placed after the name:
 
 ```mist
-let id u64 = 1000234;
+i32 mut counter = 0;
-let is_active bool = true;
+counter = 10;
-let name *str = "mist";
+```
+
+## Strings
+
+String references use `str&` for a natural left-to-right read:
+
+```mist
+str& name = "mist";
+str& greeting = "Hello";
 ```
 
 ## Arrays
@@ -43,16 +61,17 @@ let zeros = [0; 10];         // Repeat notation: ten zeroes
 
 ## Pattern Destructuring
 
-Tuples are destructured using square brackets:
+Tuples are destructured using parentheses:
 
 ```mist
-let [a, b] = (10, "hello");
+let (a, b) = (10, "hello");
-let [a, [b, c]] = (1, (2, 3));
+let (a, (b, c)) = (1, (2, 3));
 ```
 
 ## Key Characteristics
 
-- **Predictable Order**: The `let` keyword signals a binding, followed by the name, optional type, and optional value.
+- **Dual Declaration Styles**: `let` for inference, `Type name` for explicit typing.
 - **Safety First**: Immutability by default prevents accidental state changes.
 - **Zero-Cost Inference**: Type inference is handled entirely at compile time.
 - **Shadowing**: Mist supports variable shadowing within the same scope.
+- **`str&` Notation**: String references use postfix `&` for clear left-to-right reading.