definetly did not vibe code 0.0.5-alpha0

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.