definetly did not vibe code 0.0.5-alpha0

content/docs/components/functions.mdx

@@ -4,7 +4,7 @@ description: Defining execution blocks with C-style ergonomics and Rust-powered
 icon: SquareFunction
 ---
 
-Functions are the primary unit of execution in Mist. They prioritize a traditional declaration order, placing the return type before the identifier to ensure signatures remain easy to scan in complex systems.
+Functions are the primary unit of execution in Mist. They prioritize a traditional declaration order, placing the return type before the identifier.
 
 ## Basic Syntax
 
@@ -28,18 +28,15 @@ Functions are private to their module by default. The `pub` modifier exports the
 pub i32 get_version() {
     return 1;
 }
-```
 
-You can also point to a specific point (super or crate, or a custom path):
+pub(crate) i32 internal_use() {
-```mist
+    return 0;
-pub(crate) i32 get_version() {
-    return 1;
 }
 ```
 
 ## Mutable Parameters
 
-Parameters follow Rust’s ownership rules but use Mist’s local variable syntax. Use `mut` to allow a function to modify its local binding of a value.
+Use `mut` to allow a function to modify its local binding of a value.
 
 ```mist
 void update_score(i32 mut current_score, i32 bonus) {
@@ -58,9 +55,23 @@ pub str'a* choose_longer<'a, T: Display>(str'a* s1, str'a* s2, T meta) {
 }
 ```
 
+## Closures
+
+Closures are anonymous functions that can capture their environment. The return type before the pipe is optional — when omitted, the closure body uses curly braces:
+
+```mist
+var add = |i32 a, i32 b| { a + b };
+
+// With explicit return type
+Option<i32> |var v| { Some(v) }
+
+// Without return type
+var greet = |str* name| { println!("Hello {}", name) };
+```
+
 ## Attributes & Metadata
 
-Metadata is applied via the `#[attr]` syntax directly above the declaration for compiler hints or testing.
+Metadata is applied via the `#[attr]` syntax directly above the declaration.
 
 ```mist
 #[inline]
@@ -71,6 +82,7 @@ pub bool is_active(u32 id) {
 
 ## Key Characteristics
 
-* **Scannable Signatures:** Placing return types first allows for rapid identification of a function's output.
+- **Scannable Signatures**: Return types first for rapid identification of a function's output.
-* **Unified Abstraction:** Lifetimes and type constraints are declared in one location, reducing signature noise.
+- **Unified Abstraction**: Lifetimes and type constraints are declared in one location.
-* **Zero-Cost Mapping:** Every function maps directly to a Rust `fn`, maintaining performance and ecosystem compatibility.
+- **Closure Support**: Anonymous functions with optional return type annotations.
+- **Zero-Cost Mapping**: Every function maps directly to a Rust `fn`.

content/docs/components/modules-imports.mdx

@@ -0,0 +1,81 @@
+---
+title: Modules & Imports
+description: Organizing code across files with module declarations and path-based imports.
+icon: FolderTree
+---
+
+Mist organizes code through a file-system based module system with explicit path imports, similar to Rust but with a cleaner import syntax.
+
+## The Module System
+
+Each `.mist` file in `src/` corresponds to a module. The module tree mirrors the file hierarchy. Directories can be declared as submodules using `mod`.
+
+### File-Based Modules
+
+The file `src/main.mist` is the crate root. Other files are discovered through `mod` declarations or by name — no explicit declaration is needed when a file exists at a matching path.
+
+### Declaring Submodules
+
+```mist
+// src/main.mist
+mod network;
+mod database;
+```
+
+## Imports
+
+Use the `use` keyword with angle brackets to bring items from other modules or external crates into scope.
+
+```mist
+use <std::fs>;
+use <std::process>;
+use <std::path::Path>;
+use <std::collections::HashMap>;
+
+// Import specific items
+use <my_module::Helper>;
+```
+
+### Visibility
+
+Items can be re-exported with a visibility modifier on the import:
+
+```mist
+pub use <internal::format>;
+```
+
+## Sidefiles
+
+Any non-`.mist` file in `src/` (e.g., `.rs`, `.toml`, data files) is treated as a **sidefile** — it is copied directly into the output directory `.mist/src/` during transpilation. This allows you to keep Rust helper files or configuration alongside your Mist source.
+
+```text
+src/
+├── main.mist
+├── helper.rs        # copied to .mist/src/helper.rs
+└── config/
+    └── data.json    # copied to .mist/src/config/data.json
+```
+
+## Project Structure
+
+A typical Mist project looks like this:
+
+```
+my-project/
+├── Cargo.toml
+├── src/
+│   ├── main.mist
+│   ├── lib/
+│   │   ├── parser.mist
+│   │   └── helper.rs
+│   └── _header.rs
+└── .mist/
+    └── src/
+        ├── main.rs        # transpiled output
+        ├── lib/
+        │   ├── parser.rs
+        │   └── helper.rs
+        └── _header.rs
+```
+
+The `.mist/src/` directory contains the transpiled Rust output. `_header.rs` is a special file that provides IDE support for Rust Analyzer.

content/docs/components/structs.mdx

@@ -57,4 +57,4 @@ pub struct Buffer<'a, T> {
 - **Type-First Declaration**: Fields use the `type name` order to match function parameters and variable declarations.
 - **Comma-Separated Members**: Fields are separated by commas, maintaining a clean and consistent delimiter style.
 - **Rust Compatibility**: Maps 1:1 to Rust structs, ensuring zero-cost abstraction and full ecosystem interoperability.
-- **Direct Visibility**: The `pub` keyword replaces `pub` for a more consistent modifier language across the codebase.
+- **Direct Visibility**: The `pub` modifier controls access at the struct and field level.

content/docs/index.mdx

@@ -11,7 +11,7 @@ Mist is currently distributed as a Cargo crate. To get started, you'll need to h
 Run the following command to install the Mist compiler:
 
 ```bash title="Terminal"
-cargo install [email protected].3-alpha4
+cargo install [email protected].5-alpha0
 ```
 
 Once the installation finishes, verify it by checking the version:
@@ -24,20 +24,19 @@ mist version
 
 ## 2. Setting Up Your Project
 
-Mist works alongside Cargo to handle the heavy lifting. Follow these steps to prepare your environment for your first "Hello World" program.
+Mist works alongside Cargo to handle the heavy lifting. Use `init` to scaffold a new project:
-
-### Initialize a New Project
-
-If you haven't already, create a new Cargo project and navigate into the directory:
 
 ```bash title="Terminal"
 cargo new my-mist-app
 cd my-mist-app
+mist init
 ```
 
-### Configure Mist
+This creates a `src/main.mist` and wires up the output directory (`.mist/src/`) in your `Cargo.toml`.
 
-Create a `mist.json` file in your root directory. This tells the compiler where to look for your source code and where to place the generated Rust files.
+### Manual Setup
+
+If you prefer to configure things yourself, create a `mist.json` file:
 
 ```json title="mist.json"
 {
@@ -46,36 +45,13 @@ Create a `mist.json` file in your root directory. This tells the compiler where
 }
 ```
 
-### Link Cargo to Mist
+Source files go in `src/` and the transpiled output goes to `.mist/src/`. Non-Mist files in `src/` (e.g. Rust sidecar files) are copied through as-is.
-
-Since Mist compiles down to Rust, you need to point Cargo to the generated output. Update your `Cargo.toml` to include the following:
-
-```toml title="Cargo.toml"
-[[bin]]
-name = "my-mist-app"
-path = "build/main.rs"
-```
-
-You can also add `/build` to your `.gitignore`.
-
-> **Pro Tip:** create a `src/_header.rs` file with only main declared, and add this to your `Cargo.toml` (without replacing the current `[[bin]]`):
-> ```toml title="Cargo.toml"
-> # add this in [package]
-> default-run="my-mist-app-header"
->
-> # Do not replace the current [[bin]]
-> [[bin]]
-> name = "my-mist-app-header"
-> path = "src/_header.rs"
->```
->
-> And add all of the `mod`(s) from `src/main.rs`, as well as a empty `main` function, this will allow `.rs` files to be used with IDE support.
 
 ---
 
 ## 3. Your First Program
 
-Now for the fun part! Create a new file at `src/main.mist` and add the following code:
+Create a new file at `src/main.mist` and add the following code:
 
 ```mist title="src/main.mist"
 void main() {
@@ -85,28 +61,23 @@ void main() {
 
 ### Build and Run
 
-To turn your Mist code into an executable, use the `run` command:
-
 ```bash title="Terminal"
-mist run
+mist run          # or the short alias: mist r
+mist build        # or: mist b
+mist check        # or: mist c
+mist transpile    # or: mist t
 ```
 
-Or if you only want to transpile to rust (this will not give any semantic errors, only syntax errors).
-
-```bash title="Terminal"
-mist transpile
-```
-
-
 ---
 
 ## Command Reference
 
-| Command          | Description                                     |
+| Command              | Alias | Description                                     |
-| ---------------- | ----------------------------------------------- |
+| -------------------- | ----- | ----------------------------------------------- |
-| `mist run`       | Runs the project in the current directory       |
+| `mist init`          |       | Initializes a new Mist project                  |
-| `mist build`     | builds the project in the current directory     |
+| `mist run`           | `r`   | Runs the project in the current directory       |
-| `mist transpile` | transpiles the project in the current directory |
+| `mist build`         | `b`   | Builds the project in the current directory     |
-| `mist check`     | checks the project in the current directory     |
+| `mist transpile`     | `t`   | Transpiles the project in the current directory |
-| `mist version`   | prints the compiler version                     |
+| `mist check`         | `c`   | Checks the project in the current directory     |
-| `mist help`      | prints this message                             |
+| `mist version`       | `-v`  | Prints the compiler version                     |
+| `mist help`          | `-h`  | Prints this message                             |

content/docs/limitations.mdx

@@ -6,4 +6,6 @@ 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.
 
+The compiler, transpiler, and CLI are partially bootstrapped — written in Mist itself. This gives us real-world feedback on every language design decision.
+
 You may encounter weird illogical syntax errors, please report them at https://github.com/mist-go/mist/issues with the context.

content/docs/logic/control-flow.mdx

@@ -4,11 +4,11 @@ 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. While many structures can return values, they follow a strict syntax for blocks and statements.
+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 — meaning braces can be omitted for single-statement branches.
 
 ## Conditionals
 
-The `if` statement evaluates a boolean expression. It supports multiple `else if` branches and an optional `else` block.
+The `if` statement evaluates a boolean expression. Single-statement bodies don't need braces:
 
 ```mist
 if (score > 50) {
@@ -18,11 +18,17 @@ if (score > 50) {
 } else {
     println!("Fail");
 }
+
+// Single-statement body (no braces needed)
+if (is_active) println!("Running");
+
+// Expression body (soft return)
+var result = if (valid) "ok" else "err";
 ```
 
 ## Match
 
-The `match` statement provides exhaustive pattern matching. Currently, every match arm requires a block `{}` following the `=>` operator.
+The `match` statement provides exhaustive pattern matching with support for multiple patterns per arm via `|`:
 
 ```mist
 match (task_state) {
@@ -43,54 +49,57 @@ match (task_state) {
 
 ## Loops
 
-Mist supports both functional iteration and traditional low-level loop control.
+### Loop
+
+An infinite loop construct:
+
+```mist
+loop {
+    println!("forever");
+    if (done) break;
+}
+```
 
 ### C-Style For Loop
 
-For manual iteration control, Mist supports the standard three-part `for` loop: initialization, condition, and post-iteration statement.
-
 ```mist
-for (var mut i = 0; i < 10; i = i + 1;) {
+for (var mut i = 0; i < 10; i++;)
     println!("Index: {}", i);
-}
 ```
 
 ### For-In Loop
 
-The `for-in` loop iterates over collections or iterators using Mist's pattern matching system.
-
 ```mist
-for (var item in collection) {
+for (var item in collection)
     process(item);
-}
 
-// Destructuring within the loop
+for ((i32 x, i32 y) in coordinates)
-for ((i32 x, i32 y) in coordinates) {
     draw_point(x, y);
-}
+
+// Range iteration
+for (var i in 0..10)
+    println!("{}", i);
 ```
 
 ### While Loop
 
-The `while` loop continues execution as long as the parenthesized expression evaluates to `true`.
-
 ```mist
 while (active) {
     wait_for_event();
 }
+
+while (count > 0) process(count--);
 ```
 
 ## Jump Statements
 
-Execution flow can be interrupted or redirected using standard jump keywords.
-
 - **`return`**: Exits the current function, optionally passing back a value.
 - **`break`**: Terminates the innermost looping construct.
-- **`continue`**: Skips the remainder of the current loop iteration and proceeds to the next.
+- **`continue`**: Skips the remainder of the current loop iteration.
 
 ## Key Characteristics
 
-- **Pattern Integration**: Loops and match arms utilize Mist's pattern system, allowing for seamless data destructuring during iteration.
+- **Statement Bodies**: If, while, for, and loop branches can omit braces for single statements or expressions.
-- **Explicit Scoping**: Match items currently require explicit blocks, ensuring clear boundaries for variable shadowing and local logic.
+- **Soft Returns**: Expression bodies (without `;`) implicitly return their value.
-- **Familiar Iteration**: The inclusion of C-style `for` loops provides fine-grained control for performance-critical logic where simple iteration is insufficient.
+- **Pattern Integration**: Loops and match arms utilize Mist's pattern system for data destructuring.
-- **Rust-Native Safety**: Despite the procedural syntax, these structures compile to safe Rust, maintaining exhaustive checking and memory safety.
+- **Multiple Patterns**: Match arms support `|` for matching multiple patterns.

content/docs/logic/expressions.mdx

@@ -4,80 +4,123 @@ description: The building blocks of logic, from literals to complex postfix chai
 icon: Binary
 ---
 
-Expressions in Mist are the fundamental units that evaluate to a value. The syntax follows a clean **prefix → primary → postfix** chain, providing a predictable structure that maps closely to Rust's mental model.
+Expressions in Mist are the fundamental units that evaluate to a value. The syntax follows a clean **prefix -> primary -> postfix** chain, providing a predictable structure that maps closely to Rust's mental model.
 
 ## Primary Expressions
 
 Primary expressions are the starting point of any logic chain. These include literal values, paths to static members, or grouped expressions in tuples.
 
 ```mist
-// Literals and paths
 var x = 42;
 var y = Math::PI;
-
-// Tuples
 var coordinates = (10, 20, 30);
-
 ```
 
 ## Postfix Operations
 
-Postfix expressions allow you to build on a primary value. This includes calling functions, accessing fields, indexing arrays, or initializing structs.
+Postfix expressions allow you to build on a primary value with field access, calls, indexing, type casting, error propagation, and mutation operators.
 
 ```mist
-// Field access and method/function calls
 var len = list.length();
 
-// Struct initialization
 var task = Task {
     name: "Drafting",
     priority: 1,
 };
 
-// Indexing and Macro calls
 var first = items[0];
-println!("Value: {}", first); // Macro call via '!'
+println!("Value: {}", first);
+```
 
+### Increment & Decrement
+
+```mist
+var mut i = 0;
+i++;
+i--;
+```
+
+### Compound Assignments
+
+```mist
+i += 10;
+i -= 5;
+i *= 2;
+i /= 3;
+value &= mask;
+flags |= 0x01;
+```
+
+### Type Casting
+
+Use `as` to convert between compatible types:
+
+```mist
+var x = 42;
+var y = x as f64;
+```
+
+### Try Operator
+
+Propagate errors with the `?` postfix operator:
+
+```mist
+var content = fs::read_to_string(path)?;
+```
+
+### Range Operators
+
+```mist
+0..10        // exclusive range (0 to 9)
+0..=10       // inclusive range (0 to 10)
+```
+
+### Arrays
+
+Arrays are initialized with brackets, with an optional repeat notation:
+
+```mist
+var arr = [1, 2, 3];
+var zeros = [0; 10];        // ten zeroes
 ```
 
 ## Prefix Operations
 
-Prefixes modify the primary expression that follows them. Mist uses these for logical negation, dereferencing, and creating references.
+Prefixes modify the primary expression that follows them.
 
 ```mist
 var mut value = 10;
 
-var ref = &value;         // Reference
+var ref = &value;
-var mref = &mut value;    // Mutable reference
+var mref = &mut value;
-var val = *ref;           // Dereference
+var val = *ref;
-var is_false = !true;     // Logical NOT
+var is_false = !true;
-
+var neg = -42;
 ```
 
 ## Binary Operations
 
-Binary operations are applied as postfixes to an expression, following a `bin_op ~ expr` pattern. This supports all standard arithmetic, comparison, and logical operators.
-
 ```mist
 var sum = 10 + 20;
 var is_equal = (x == y);
 var complex = (a + b) * (c / d);
-
 ```
 
 ## Operator Table
 
-Mist supports the following binary operators for comparisons and arithmetic:
+| Category       | Operators                                                        |
-
+| -------------- | ---------------------------------------------------------------- |
-| Category       | Operators                        |
+| **Arithmetic** | `+`, `-`, `*`, `/`, `%`                                          |
-| -------------- | -------------------------------- |
+| **Comparison** | `==`, `!=`, `<`, `>`, `<=`, `>=`                                  |
-| **Arithmetic** | `+`, `-`, `*`, `/`, `%`          |
+| **Logical**    | `&&`, `||`                                                        |
-| **Comparison** | `==`, `!=`, `<`, `>`, `<=`, `>=` |
+| **Bitwise**    | `<<`, `>>`, `&`, `\|`, `^`                                        |
-| **Logical**    | `&&`, `\|\|`                     |
+| **Range**      | `..`, `..=`                                                       |
+| **Assign**     | `=`, `+=`, `-=`, `*=`, `/=`, `%=`, `&=`, `\|=`, `^=`, `<<=`, `>>=` |
 
 ## Key Characteristics
 
-- **Predictable Chaining**: The `prefix* ~ primary ~ postfix*` grammar ensures that complex expressions are parsed consistently, whether you are dereferencing a function call or indexing a struct field.
+- **Predictable Chaining**: The `prefix* ~ primary ~ postfix*` grammar ensures complex expressions are parsed consistently.
-- **Rust-Style References**: While the pointer syntax `type*` is used in declarations, expressions use `&` and `&mut` to create references, maintaining compatibility with Rust's borrow checker.
+- **Rust-Style References**: Expressions use `&` and `&mut` to create references, maintaining borrow checker compatibility.
-- **Macro Integration**: Macros are treated as a postfix operation (`!`), allowing them to be called on identifiers just like standard functions.
+- **Macro Integration**: Macros use `!` as a postfix operation.
-- **Unified Tuples**: Tuples are primary expressions, allowing them to be passed, returned, or destructured seamlessly within the expression tree.
+- **Type Casting**: `as Type` provides explicit type conversion at the expression level.
+- **Error Propagation**: The `?` operator enables early returns for `Result`/`Option` types.

content/docs/logic/variables.mdx

@@ -11,8 +11,8 @@ In Mist, variables follow the language-wide `type name` convention. For local sc
 Variables are declared using the `var` keyword for automatic type inference. Like Rust, variables are immutable by default.
 
 ```mist
-var message = "Hello Mist"; // Inferred as str*
+var message = "Hello Mist";
-var count = 42;             // Inferred as i32
+var count = 42;
 ```
 
 ## Mutability
@@ -29,28 +29,28 @@ price = 14.99;
 
 ## Explicit Typing
 
-While `var` handles inference, you can explicitly define the type before the identifier. This is often used for clarity in complex logic or when the specific numeric width (e.g., `u8` vs `i32`) matters.
-
 ```mist
 u64 large_id = 1000234;
 bool is_active = true;
 ```
 
-## Pattern Destructuring
+## Arrays
-
-Because variable declarations are patterns, you can destructure tuples or structures directly. This keeps data extraction clean and avoids manual indexing.
 
 ```mist
-// Destructuring a tuple into local variables
+var list = [1, 2, 3];       // Standard init
-(i32, i32) (x, y) = get_coordinates();
+var zeros = [0; 10];         // Repeat notation: ten zeroes
+```
 
-// Using 'var' within a pattern for inference
+## Pattern Destructuring
+
+```mist
+(i32, i32) (x, y) = get_coordinates();
 (String, i32) (name, age) = get_user_info();
 ```
 
 ## Constants
 
-Constants are immutable values that are evaluated at compile time. They require an explicit type and follow the `const` keyword.
+Constants are immutable values evaluated at compile time with an explicit type.
 
 ```mist
 const i32 MAX_RETRIES = 5;
@@ -59,7 +59,7 @@ const str* VERSION = "1.0.4";
 
 ## Key Characteristics
 
-- **Predictable Order**: Whether using `var` or an explicit type, the name of the variable always follows the "source" of its data.
+- **Predictable Order**: Whether using `var` or an explicit type, the name always follows the "source" of its data.
-- **Safety First**: Immutability by default prevents accidental state changes, mapping directly to Rust's memory safety model.
+- **Safety First**: Immutability by default prevents accidental state changes.
-- **Zero-Cost Inference**: Type inference is handled entirely at compile time, ensuring there is no runtime performance penalty.
+- **Zero-Cost Inference**: Type inference is handled entirely at compile time.
-- **Shadowing**: Mist supports variable shadowing, allowing you to reuse variable names within the same scope to transform data without changing mutability.
+- **Shadowing**: Mist supports variable shadowing within the same scope.

content/docs/meta.json

@@ -12,10 +12,11 @@
         "components/classes",
         "components/traits",
         "components/pointers-references",
+        "components/modules-imports",
 
         "---[ArrowDownUp]Logic---",
         "logic/variables",
         "logic/control-flow",
         "logic/expressions"
     ]
-}
+}

content/docs/philosophy.mdx

@@ -34,6 +34,10 @@ Mist is not a replacement for Rust; it is a **ergonomic interface** for it. It p
 
 ---
 
+## Bootstrapped Development
+
+Mist is partially bootstrapped — the compiler's CLI, transpiler, and analyzer modules are written in Mist itself. This gives us first-hand experience with the language's ergonomics and drives real-world improvements with every release.
+
 ## Why Mist?
 
 Mist is for the developer who needs the rigor of a systems language but wants the comfort of a modern, streamlined environment.