Docs rewrite

content/docs/guide/architecture.mdx

@@ -0,0 +1,48 @@
+---
+title: Compiler Architecture
+description: High-level pipeline overview of the Mist compiler and crate organization.
+icon: Building2
+---
+
+### Pipeline Overview
+
+The Mist compiler operates in distinct phases:
+
+```
+Source (.mist)
+    │
+    ▼
+┌─────────────┐
+│   Lexer     │  (pest PEG grammar)
+│   & Parser  │
+└─────────────┘
+    │  AST
+    ▼
+┌─────────────┐
+│  Semantics  │  (field init checking)
+└─────────────┘
+    │
+    ▼
+┌─────────────┐
+│  Codegen    │  (AST → Rust source)
+└─────────────┘
+    │  .rs + .map.json
+    ▼
+┌─────────────┐
+│    cargo    │  (Rust compilation)
+└─────────────┘
+    │
+    ▼
+  Binary / Library
+```
+
+### Crate Organization
+
+The compiler is written in Rust and Mist itself, organized into four main crates:
+
+| Crate | Language | Role |
+|-------|----------|------|
+| **mist-parser** | Rust | PEG parsing via pest, AST construction, semantic checks, position mapping |
+| **mist-codegen** | Rust | AST → Rust source code generation |
+| **mist-analyzer** | Rust | Language server bridging mist-editor ↔ rust-analyzer |
+| **mist-api** | Mist | Orchestrates transpilation, module tree building, cargo invocation, error remapping |

content/docs/guide/attributes.mdx

@@ -0,0 +1,32 @@
+---
+title: Attributes
+description: Inner and outer attributes for modules, items, and metadata.
+icon: Hash
+---
+
+Inner attributes apply to the containing module:
+
+```mist
+#![allow(unused_variables)]
+```
+
+Outer attributes apply to the next item:
+
+```mist
+#[derive(Debug, Clone)]
+struct Point {
+    i32 x,
+    i32 y,
+}
+
+#[test]
+void my_test()
+{
+    assert_eq!(1, 1);
+}
+```
+
+Attribute syntax:
+- `#[path]`
+- `#[path = literal]`
+- `#[path(item1, item2, ...)]`

content/docs/guide/classes.mdx

@@ -0,0 +1,69 @@
+---
+title: Classes
+description: Class declarations, constructors, inheritance, virtual dispatch, and the override keyword.
+icon: Shapes
+---
+
+Mist introduces `class` as syntactic sugar for a Rust struct with a virtual method table (vtable).
+
+```mist
+pub class Animal {
+    str& name,
+
+    pub constructor(str& name)
+    {
+        self.name = name;
+    }
+
+    pub void speak(&self)
+    {
+        println!("...");
+    }
+}
+```
+
+Class fields can have default initializers:
+
+```mist
+class Player {
+    i32 health = 100,
+    str& name,
+}
+```
+
+### Inheritance
+
+```mist
+class Dog : Animal {
+    pub constructor(str& name)
+    {
+        super(name);
+    }
+
+    override void speak(&self)
+    {
+        println!("Woof!");
+    }
+}
+```
+
+The `override` keyword supports explicit base class targeting:
+
+```mist
+override(Animal) void speak(&self)
+{
+    println!("Woof!");
+}
+```
+
+### Under the Hood
+
+A class `Dog : Animal` generates:
+
+1. A Rust struct with a `_super: Animal` field (or `_vptr: &'static [*const c_void]` for root classes)
+2. A vtable constant with function pointers for each public method
+3. An `impl` block with `Deref<Target = Animal>` and `DerefMut`
+4. Method trampolines (`__m_<name>`) that are dispatched through the vtable
+5. A `new()` constructor that initializes via `MaybeUninit` and calls the user's `constructor(&mut self)`
+
+The vtable is unified: parent entries are copied, overridden entries replace parent slots, and new methods are appended.

content/docs/guide/control-flow.mdx

@@ -0,0 +1,87 @@
+---
+title: Control Flow
+description: If/else, while, for, c-style for, loop, match, break, continue, and return.
+icon: ArrowLeftRight
+---
+
+### If/Else
+
+```mist
+if condition {
+    // body
+} else if other_condition {
+    // body
+} else {
+    // body
+}
+```
+
+Conditions must be parenthesized: `if (expr) { }` or `if expr_no_struct { }` (struct literals require parentheses).
+
+Used as an expression:
+
+```mist
+let x = if true { 1 } else { 2 };
+```
+
+### While
+
+```mist
+while condition {
+    // body
+}
+```
+
+### For
+
+```mist
+for pattern in iterator {
+    // body
+}
+
+for i in 0 .. 10 {
+    // body
+}
+```
+
+### C-Style For
+
+```mist
+for (let mut i = 0; i < 10; i++) {
+    // body
+}
+```
+
+### Loop
+
+```mist
+loop {
+    // infinite loop
+}
+```
+
+### Match
+
+```mist
+match value {
+    pattern1 => expr,
+    pattern2 => {
+        // block body
+    }
+    pattern3 | pattern4 => expr,
+}
+```
+
+### Break / Continue
+
+```mist
+break;
+continue;
+```
+
+### Return
+
+```mist
+return;
+return value;
+```

content/docs/guide/functions.mdx

@@ -0,0 +1,58 @@
+---
+title: Functions
+description: Function declarations, self parameters, return types, and unsafe functions.
+icon: Function
+---
+
+```mist
+// Return type is `void` (unit)
+void greet(str& name)
+{
+    println!("Hello, {name}");
+}
+
+// With return type
+i32 add(i32 a, i32 b)
+{
+    return a + b;
+}
+
+// Expression body (last expression is the return value)
+i32 square(i32 x)
+{
+    x * x
+}
+
+// Public function
+pub i32 multiply(i32 a, i32 b)
+{
+    a * b
+}
+
+// Generic function
+T identity<T>(T value)
+{
+    value
+}
+
+// Unsafe function
+unsafe i32 dangerous()
+{
+    42
+}
+```
+
+Function syntax: `[pub] [void | <type>] <name>[<generics>](<params>) [override] { <body> }`
+
+Functions use **Allman brace style** (opening brace on the next line).
+
+### Self Parameter
+
+Methods can take `self`, `&self`, `&mut self`, or `self` with lifetimes:
+
+```mist
+pub void set_value(&mut self, i32 v)
+{
+    self.value = v;
+}
+```

content/docs/guide/generics.mdx

@@ -0,0 +1,39 @@
+---
+title: Generics
+description: Generic functions, structs, enums, trait bounds, and lifetimes.
+icon: Braces
+---
+
+```mist
+// Generic function
+T id<T>(T x)
+{
+    x
+}
+
+// Generic struct
+struct Pair<A, B> {
+    A first,
+    B second,
+}
+
+// Generic enum
+enum Result<T, E> {
+    Ok(T),
+    Err(E),
+}
+
+// Generic with trait bounds
+T max<T : Ord>(T a, T b)
+{
+    if a > b { a } else { b }
+}
+
+// Lifetime generics
+void process<'a>(&'a str& data)
+{
+    // ...
+}
+```
+
+Generic syntax uses `<` `>` delimiters. Lifetimes are prefixed with `'`.

content/docs/guide/modules.mdx

@@ -0,0 +1,29 @@
+---
+title: Modules & Imports
+description: Module declarations, imports, re-exports, and module resolution rules.
+icon: FolderTree
+---
+
+```mist
+// Declare a submodule
+pub module foo;
+
+// Import
+use std::collections::HashMap;
+
+// Re-exporting import
+pub use my_module::MyType;
+```
+
+### Module Resolution
+
+Mist maps the module tree to Rust's module system:
+
+| Mist Path                    | Rust Output                  |
+|------------------------------|------------------------------|
+| `src/main.mist`              | `.mist/src/main.rs`          |
+| `src/utils/package.mist`     | `.mist/src/utils/mod.rs`     |
+| `src/foo.mist`               | `.mist/src/foo.rs`           |
+| `src/utils/helper.mist`      | `.mist/src/utils/helper.rs`  |
+
+A `package.mist` file acts as a directory's module root, analogous to `mod.rs`.

content/docs/guide/operators.mdx

@@ -0,0 +1,98 @@
+---
+title: Operators, Macros & Closures
+description: Binary, prefix, and postfix operators, macro calls, and closure expressions.
+icon: Plus
+---
+
+### Binary Operators
+
+| Operator | Description          |
+|----------|----------------------|
+| `+`      | Addition             |
+| `-`      | Subtraction          |
+| `*`      | Multiplication       |
+| `/`      | Division             |
+| `%`      | Modulus              |
+| `==`     | Equality             |
+| `!=`     | Inequality           |
+| `<`      | Less than            |
+| `>`      | Greater than         |
+| `<=`     | Less or equal        |
+| `>=`     | Greater or equal     |
+| `&&`     | Logical AND          |
+| `\|\|`   | Logical OR           |
+| `&`      | Bitwise AND          |
+| `\|`     | Bitwise OR           |
+| `^`      | Bitwise XOR          |
+| `<<`     | Left shift           |
+| `>>`     | Right shift          |
+| `=`      | Assignment           |
+| `+=`     | Add assign           |
+| `-=`     | Subtract assign      |
+| `*=`     | Multiply assign      |
+| `/=`     | Divide assign        |
+| `%=`     | Modulus assign       |
+| `&=`     | Bitwise AND assign   |
+| `\|=`    | Bitwise OR assign    |
+| `^=`     | Bitwise XOR assign   |
+| `<<=`    | Left shift assign    |
+| `>>=`    | Right shift assign   |
+| `..`     | Range (exclusive)    |
+| `..=`    | Range (inclusive)    |
+| `->`     | Pointer write        |
+
+### Prefix Operators
+
+| Operator | Description       |
+|----------|-------------------|
+| `*`      | Dereference       |
+| `&`      | Reference         |
+| `&mut`   | Mutable reference |
+| `!`      | Logical NOT       |
+| `-`      | Numeric negation  |
+
+### Postfix Operators
+
+| Operator   | Description          |
+|------------|----------------------|
+| `.field`   | Field access         |
+| `.0`       | Tuple field access   |
+| `()`       | Function call        |
+| `[]`       | Index                |
+| `{ f: v }` | Struct literal       |
+| `as Type`  | Type cast            |
+| `?`        | Try (error prop)     |
+| `++`       | Increment            |
+| `--`       | Decrement            |
+| `!()`      | Macro call (paren)   |
+| `![]`      | Macro call (bracket) |
+| `!{}`      | Macro call (brace)   |
+
+### Macros
+
+Mist reuses Rust's macro system directly:
+
+```mist
+println!("hello");
+assert_eq!(a, b);
+vec![1, 2, 3];
+```
+
+Macro calls use `!` followed by parentheses, brackets, or braces.
+
+### Closures
+
+```mist
+let add = (a, b) => a + b;
+let result = add(2, 3);  // 5
+
+let square = f64 x => x * x;
+```
+
+Closures can have explicit return types:
+
+```mist
+let transform = i32 x => {
+    x * 2
+};
+```

content/docs/guide/patterns.mdx

@@ -0,0 +1,41 @@
+---
+title: Patterns
+description: Pattern matching with literals, tuples, structs, named tuples, wildcards, and mutable bindings.
+icon: Split
+---
+
+```mist
+// Literal patterns
+match x {
+    1 => "one",
+    2 => "two",
+    _ => "other",
+}
+
+// Tuple patterns
+let (a, b) = (1, 2);
+
+// Struct patterns
+match value {
+    Point { x, y } => x + y,
+    Point { x: 0, y } => y,
+    _ => 0,
+}
+
+// Named tuple patterns (newtype)
+let MyType(value) = my_var;
+
+// Wildcard / etc
+let _ = get_side_effect();
+match x {
+    1 => ...,
+    .. => ...,  // rest / etc
+}
+
+// Mutable binding in pattern
+let mut x = 42;
+match ref_to_option {
+    Some(mut value) => value += 1,
+    None => {},
+}
+```

content/docs/guide/structs-enums.mdx

@@ -0,0 +1,47 @@
+---
+title: Structs & Enums
+description: Defining structs and enums with named, tuple, and struct variants.
+icon: Box
+---
+
+### Structs
+
+```mist
+pub struct Point {
+    i32 x,
+    i32 y,
+}
+
+pub struct Generic<T> {
+    T value,
+}
+```
+
+Fields can be public or private:
+
+```mist
+struct User {
+    pub str& name,
+    i32 age,  // private
+}
+```
+
+### Enums
+
+```mist
+pub enum Option<T> {
+    Some(T),
+    None,
+}
+
+pub enum Message {
+    Quit,
+    Move(i32, i32),
+    Write { str& content, i32 length },
+}
+```
+
+Enum variants can be:
+- **Named** — `Variant`
+- **Tuple** — `Variant(T1, T2)`
+- **Struct** — `Variant { T1 field1, T2 field2 }`

content/docs/guide/syntax-overview.mdx

@@ -0,0 +1,45 @@
+---
+title: Syntax Overview
+description: Comments, literals, identifiers, and keywords in Mist.
+icon: Code
+---
+
+### Comments
+
+```mist
+// Line comments only
+```
+
+### Literals
+
+```mist
+42              // Integer
+3.14            // Float
+true            // Boolean
+false           // Boolean
+"hello"         // String
+(1, true, "x")  // Tuple
+```
+
+### Identifiers & Keywords
+
+Keywords are reserved and cannot be used as identifiers:
+
+`if`, `else`, `fn`, `for`, `while`, `match`, `return`, `break`, `continue`, `struct`, `enum`, `class`, `trait`, `impl`, `use`, `pub`, `mut`, `let`, `true`, `false`, `dyn`, `loop`, `unsafe`, `override`, `const`, `type`
+
+Identifiers follow the pattern `[a-zA-Z_][a-zA-Z0-9_]*`.
+
+### Visibility
+
+```mist
+// Private (default)
+void internal() { }
+
+// Public
+pub void external() { }
+
+// Public to specific path
+pub(crate) void crate_only() { }
+pub(super) void parent_only() { }
+pub(in my::module) void module_only() { }
+```

content/docs/guide/traits-impls.mdx

@@ -0,0 +1,42 @@
+---
+title: Traits & Impls
+description: Defining traits, trait bounds, and implementation blocks.
+icon: Puzzle
+---
+
+### Traits
+
+```mist
+pub trait Drawable {
+    void draw(&self);
+}
+
+pub trait Comparable<T> : Eq {
+    i32 cmp(&self, T other);
+}
+```
+
+Trait requirements are specified after `:`:
+
+```mist
+trait MyTrait : SuperTrait + OtherTrait {
+    void required_method(&self);
+    void another(&self);
+}
+```
+
+### Impl Blocks
+
+```mist
+impl MyType {
+    void method(&self) { }
+}
+
+impl Trait for MyType {
+    void method(&self) { }
+}
+
+impl<T> GenericTrait<T> for MyType {
+    void method(&self, T value) { }
+}
+```

content/docs/guide/types.mdx

@@ -0,0 +1,47 @@
+---
+title: Types
+description: The Mist type system including references, pointers, tuples, function types, and trait objects.
+icon: Type
+---
+
+### Type System
+
+```mist
+i32                // Path type
+str&               // Reference type
+&mut i32           // Mutable reference
+&'a i32            // Reference with lifetime
+*const i32         // Const pointer
+*mut i32           // Mutable pointer
+(i32, bool)        // Tuple type
+fn(i32) -> bool    // Function pointer type
+Fn(i32) -> bool    // Closure trait (Fn)
+FnMut(i32) -> bool // Closure trait (FnMut)
+FnOnce(i32) -> bool // Closure trait (FnOnce)
+dyn Trait          // Trait object
+void               // Unit type (maps to Rust's ())
+'lifetime          // Lifetime
+```
+
+Type expressions can be composed:
+
+```mist
+type_expr = { (void | path_type | tuple_type | dyn_type) ~ (unsafe_ref_type | ref_type | fn_type)* }
+```
+
+This means types are written left-to-right naturally:
+
+```mist
+i32&              // &i32
+i32&mut           // &mut i32
+i32&'a            // &'a i32
+i32 fn() -> bool  // fn(i32) -> bool
+```
+
+### Type Aliases
+
+```mist
+type MyInt = i32;
+
+type Result<T> = std::result::Result<T, str&>;
+```

content/docs/guide/variables.mdx

@@ -0,0 +1,30 @@
+---
+title: Variables
+description: Variable declarations, mutability, type annotations, and destructuring.
+icon: Variable
+---
+
+```mist
+let x = 42;                    // Type-inferred immutable
+let mut y = 10;                // Mutable variable
+i32 z = 100;                   // Explicit type annotation
+str& s = "hello";              // Typed string reference
+bool b = true;                 // Typed boolean
+f64 f = 3.14;                  // Typed float
+let (a, b) = (1, "two");      // Destructuring
+let (x, (y, z)) = (1, (2, 3)); // Nested destructuring
+```
+
+Variable declarations follow either of two forms:
+
+```mist
+let <pattern> [= <expr>];
+<type> <pattern> [= <expr>];
+```
+
+### Const and Static
+
+```mist
+const MAX: i32 = 100;
+static NAME: str& = "hello";
+```