Update: Philosphy and index

content/docs/index.mdx

@@ -8,12 +8,16 @@ icon: Rocket
 
 Mist is currently distributed as a Cargo crate. To get started, you'll need to have the Rust toolchain installed.
 
-Run the following command to install the Mist compiler:
+Run the following command to install the Mist toolchain:
 
 ```bash title="Terminal"
-cargo install [email protected].1-alpha.0
+cargo install [email protected].7-alpha.0
 ```
 
+> (ℹ) For a more streamlined development experience, Install the following VSCode extensions:
+> 1. [Mist syntax highlighting VSCode extension](https://marketplace.visualstudio.com/items?itemName=selimaj-dev.mist-syntax)
+> 2. [Mist analyzer LSP VSCode extension](https://marketplace.visualstudio.com/items?itemName=selimaj-dev.mist-analyzer)
+
 Once the installation finishes, verify it by checking the version:
 
 ```bash title="Terminal"
@@ -22,39 +26,39 @@ mist version
 
 ---
 
-## 2. Setting Up Your Project
+## 2. Setting Up Your Cargo Project
 
-Mist works alongside Cargo to handle the heavy lifting. Use `init` to scaffold a new project:
+Mist works alongside Cargo to handle the heavy lifting. Use `cargo new` or `cargo init` to scaffold a new project:
 
 ```bash title="Terminal"
 cargo new my-mist-app
 cd my-mist-app
-mist init
 ```
 
 This creates a `src/main.mist` and wires up the output directory (`.mist/src/`) in your `Cargo.toml`.
 
-### Manual Setup
+### 3. Adding mist to your Cargo project
 
-If you prefer to configure things yourself, create a `mist.json` file:
+Mist needs a `Mist.toml` in the root of the project (Alongside `Cargo.toml`) to know what to transpile as the main file (eg. main.mist, lib.mist).
 
-```json title="mist.json"
+```toml title="Mist.toml"
-{
+# main.mist is now the main package
-  "src": "src",
+package = "main.mist"
-  "output": "build"
+
-}
+# Side packages that work as cargo binaries
+packages = []
 ```
 
 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.
 
 ---
 
-## 3. Your First Program
+## 4. Your First Program
 
 Create a new file at `src/main.mist` and add the following code:
 
 ```mist title="src/main.mist"
-fn main() {
+void main() {
     println!("Hello World!");
 }
 ```
@@ -62,7 +66,7 @@ fn main() {
 ### Build and Run
 
 ```bash title="Terminal"
-mist run          # or the short alias: mist r
+mist run          # or: mist r
 mist build        # or: mist b
 mist check        # or: mist c
 mist transpile    # or: mist t
@@ -74,7 +78,7 @@ mist transpile    # or: mist t
 
 | Command              | Alias | Description                                     |
 | -------------------- | ----- | ----------------------------------------------- |
-| `mist init`          |       | Initializes a new Mist project                  |
+| `mist init`          |       | Initializes a new Mist project (Deprecated)     |
 | `mist run`           | `r`   | Runs the project in the current directory       |
 | `mist build`         | `b`   | Builds the project in the current directory     |
 | `mist transpile`     | `t`   | Transpiles the project in the current directory |

content/docs/philosophy.mdx

@@ -4,33 +4,71 @@ description: The mindset, ergonomics, and feeling of writing Mist.
 icon: Brain
 ---
 
-**Mist** is a systems programming language designed for those who value the "craft" of software. It is built to provide a serene, tactile authoring environment that stays out of your way, allowing you to focus entirely on the architecture of your solution.
+**Mist** is a pragmatic systems programming language built on Rust. It uses C/C++ style syntax for quick onboarding while compiling directly to efficient Rust code with zero-cost abstractions and no runtime overhead.
 
-By compiling directly to Rust, Mist offers a refined surface layer that maintains industrial-grade safety and performance while prioritizing a flow state that is often lost in modern systems development.
+All of your favorite Rust libraries work with Mist. It is designed for **low-level applications and embedded programming**, where a type-first approach is preferred and staying close to the metal matters.
 
 ---
 
-## The Philosophy of Ergonomics
+## C++ You Know, Rust You Trust
 
-Writing Mist should feel intentional and deeply satisfying. It is built on the belief that systems programming is at its best when it is **calm, predictable, and direct**.
+Mist is meant to feel like C++ but **be** Rust. It bridges the gap between the ergonomics of a classic systems language and the safety guarantees of Rust's ownership model.
 
-### Reducing Expression Overhead
+### Type-First Syntax
 
-Complexity often arises from "expression overhead"—the mental energy spent navigating intricate syntax and symbols. Mist reduces this friction by:
+Low-level and embedded development demands clarity about what your data is. Mist puts the **type first** — before the name — so declarations read naturally:
 
-* **Predictable Flow:** By adopting a consistent `name: Type` convention, code follows a natural rhythm that is easy to write and instantly scannable.
+```mist
-* **Structural Clarity:** Features like unified `class` blocks and explicit `constructor` keywords provide a clear, organized home for your logic, reducing the need to jump between disparate files or implementation blocks.
+i32 score = 100;
-* **Tactile Precision:** Every symbol, from `*mut` pointers to pattern-based variables, is designed to feel physically connected to the data it represents, making the "mechanics" of the language feel like a well-calm tool in your hand.
+Vec<String> args = env::args().collect();
+void* data = allocate(size);
+```
+
+This mirrors C/C++ declaration syntax, making Mist instantly familiar to embedded and systems programmers while compiling into Rust's strict type system.
+
+### C-Style Functions
+
+Functions use the return type before the name — no `fn` keyword needed:
+
+```mist
+i32 add(i32 a, i32 b) {
+    a + b
+}
+
+void log(message *str) {
+    println!("{}", message);
+}
+```
+
+Every function maps directly to a Rust `fn` underneath.
+
+### Minimal Friction
+
+* No `let` keyword — `Type name = value` is all you need.
+* Consistent `name Type` convention across parameters, fields, and locals.
+* Explicit pointers with `*T` and `*mut T` — clear intent without ceremony.
+* String references use `str&` for a natural left-to-right read.
+
+---
+
+## Built for Low-Level and Embedded
+
+Mist is designed from the ground up for systems where resources are constrained and control is required:
+
+* **No runtime** — no garbage collector, no hidden allocator, no VM.
+* **Direct memory control** — explicit pointers, manual allocation, predictable layout.
+* **Zero-cost abstractions** — classes, traits, and generics all resolve at compile time.
+* **Works with existing Cargo tooling** — use any Rust crate as a library.
 
 ---
 
 ## A Transparent Surface Layer
 
-Mist is not a replacement for Rust; it is a **ergonomic interface** for it. It provides a way to interact with the world’s most powerful systems model through a cleaner lens.
+Mist is not a replacement for Rust; it is an **ergonomic interface** for it. It provides a way to interact with the world's most powerful systems model through a cleaner lens.
 
-* **Zero-Cost Abstractions:** Every high-level structure in Mist—whether it’s a class, an enum variant, or a trait implementation—maps directly to an optimized Rust primitive. There is no "magic," no hidden runtime, and no garbage collector.
+* **Zero-Cost Abstractions:** Every high-level structure in Mist — classes, enums, traits — maps directly to optimized Rust primitives. No magic, no hidden runtime.
-* **Grounded Safety:** Mist doesn't hide memory safety; it makes it easier to express. You retain the full power of the borrow checker, but with a syntax that feels like a classic, high-performance toolkit.
+* **Grounded Safety:** Mist doesn't hide memory safety; it makes it easier to express. You retain the full power of the borrow checker with syntax that feels like classic C++.
-* **Native Fluency:** Because Mist compiles to idiomatic, readable Rust, it is a first-class citizen of the ecosystem. You can utilize any existing crate while writing code that feels uniquely "Mist".
+* **Native Fluency:** Mist compiles to idiomatic, readable Rust, making it a first-class citizen of the ecosystem. Use any crate while writing code that feels distinctly Mist.
 
 ---
 
@@ -40,8 +78,7 @@ Mist is partially bootstrapped — the compiler's CLI, transpiler, and analyzer
 
 ## Why Mist?
 
-Mist is for the developer who needs the rigor of a systems language but wants the comfort of a modern, streamlined environment.
+* **Familiarity:** C/C++ developers can be productive immediately — no new optical model to learn.
-
+* **Safety:** Rust's borrow checker and type system under every expression, no exceptions.
-* **Mental Longevity:** Designed for large-scale codebases where readability is paramount to long-term maintenance.
+* **Control:** Explicit types, explicit pointers, explicit allocation — nothing hidden.
-* **Direct Control:** You stay close to the metal, but the language handles the "noise" of idiomatic expression.
+* **Ecosystem:** The entire Rust crate ecosystem available at your fingertips.
-* **Craftsmanship:** Mist is where the discipline of systems programming meets the comfort of a high-end workshop.