Docs rewrite

content/docs/internals/builder.mdx

@@ -0,0 +1,34 @@
+---
+title: Builder & Error Remapping
+description: How Mist invokes cargo and remaps Rust compiler errors back to Mist source locations.
+icon: Bug
+---
+
+The builder module (`builder.mist` in the `mist_api` crate) wraps `cargo` to:
+
+1. Spawn `cargo` with `--message-format=json`
+2. Parse JSON compiler messages
+3. For each diagnostic span, look up the corresponding `.map.json` file
+4. Remap Rust line/column to Mist line/column using the mapping
+5. Display errors/warnings with Mist source locations and context lines
+
+```rust
+pub fn build(args: Vec<String>, root: PathBuf) -> bool {
+    // Spawn cargo with JSON output
+    // Parse CompilerMessage for each span
+    // Look up rev_mapper::Mapping from .map.json
+    // Remap to Mist positions
+    // Print diagnostics
+}
+```
+
+### Diagnostic Output
+
+Errors and warnings are displayed with Mist source context:
+
+```
+src/main.mist:10:5
+ Error: mismatched types
+    let x: i32 = "hello";
+                ^^^^^^^
+```