From c85b0d85452ce6749fbe37896a37b31b6766665f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Thales=20de=20Fran=C3=A7a?= <thales.franca@nubank.com.br>
Date: Sat, 21 Mar 2026 21:18:52 -0300
Subject: [PATCH] docs: update README with improved writing and documentation
 references

Add dependency management doc reference, multiple code examples,
clearer architecture section, and reorganize content for readability.
---
 README.md | 53 +++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 41 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 62f69ec..50e27a0 100644
--- a/README.md
+++ b/README.md
@@ -8,19 +8,41 @@ A statically typed Lisp for building MCP servers. The compiler is written in Rus
 
 ## Overview
 
-Vex uses S-expression syntax with compile-time type checking, targeting networked services — especially [MCP](https://modelcontextprotocol.io/) servers. The compiler pipeline (lexer → parser → macro expand → type checker → codegen) produces Go source that `go build` compiles to a native binary.
+Vex combines S-expression syntax with compile-time type checking, targeting networked services — especially [MCP](https://modelcontextprotocol.io/) servers. The compiler pipeline produces Go source that `go build` compiles to a native binary. An alternative path runs code directly through a tree-walking interpreter for the REPL.
 
-## Example
+## Examples
 
 ```lisp
 (defn main []
   (println "Hello, World!"))
 ```
 
+```lisp
+(defn fib [n : Int] : Int
+  (if (<= n 1)
+    n
+    (+ (fib (- n 1)) (fib (- n 2)))))
+
+(defn main []
+  (println (str "fib(10) = " (fib 10))))
+```
+
+```lisp
+(deftype Point (x Float) (y Float))
+
+(defn distance [p : Point] : String
+  (str "(" (. p x) ", " (. p y) ")"))
+
+(defn main []
+  (let [origin (Point 0.0 0.0)
+        target (Point 3.0 4.0)]
+    (println (str "origin = " (distance origin)))
+    (println (str "target = " (distance target)))))
+```
+
 ## Usage
 
 ```bash
-cargo build
 vex build hello.vx              # Compile to ./hello binary
 vex build hello.vx -o server    # Custom output name
 vex build hello.vx --emit-go .  # Also write generated Go source
@@ -30,7 +52,7 @@ vex repl                        # Interactive REPL
 
 ## Current Status
 
-All compiler phases are implemented. The self-hosted macro system (`defmacro`) supports user-defined compile-time macros with automatic hygiene.
+All compiler phases are implemented and pass 551 tests. The self-hosted macro system (`defmacro`) supports user-defined compile-time macros with automatic hygiene.
 
 ### Compiler Phases
 
@@ -48,26 +70,33 @@ All compiler phases are implemented. The self-hosted macro system (`defmacro`) s
 | `interpreter.rs` — HIR → Value (tree-walking eval) | Done |
 | `lib.rs` / `main.rs` — Full pipeline, CLI | Done |
 
-### Implemented Features
+### Language Features
 
 - **Primitives:** integers, floats, strings, booleans, nil
 - **Functions:** `defn`, `def`, `fn` (lambdas), higher-order functions
 - **Control flow:** `if`, `cond`, `and`, `or`, `let`, pattern matching (`match`)
-- **Macros:** `defmacro`, `quote`, `unquote`, `splice`, macro helpers (`syntax-list`, `syntax-cons`, etc.), automatic hygiene via `gensym`
-- **Data types:** records (`deftype`), field access (`.`), record constructors, unions (`defunion`)
+- **Macros:** `defmacro`, `quote`, `unquote`, `splice`, macro helpers, automatic hygiene via `gensym`
+- **Data types:** records (`deftype`), field access (`.`), unions (`defunion`)
 - **Built-in types:** `Option`, `Result`, `List`, `Map`
 - **Collections:** `each`, `range`, `map`, `filter`
 - **Modules:** `module`, `export`, `import`, Go interop (`import-go`)
 - **Concurrency:** `spawn`, `channel`, `send`, `recv`
 - **REPL:** interactive `vex repl` with multi-line input and persistent state
-- **Interpreter:** tree-walking HIR evaluator with all expression forms
-- **Built-in functions:** `println`, `str`, `mod`, arithmetic/comparison operators
+- **Built-in functions:** `println`, `str`, `mod`, arithmetic and comparison operators
 
 ## Architecture
 
-- Pipeline: Source → Lexer → Parser → Macro Expand → Type Checker → Codegen → `go build` → Binary
-- Alternative: Source → Lexer → Parser → Macro Expand → Type Checker → Interpreter (direct eval)
-- Design docs: [`docs/language-design.md`](docs/language-design.md), [`docs/compiler-architecture.md`](docs/compiler-architecture.md)
+```
+Source → Lexer → Parser → Macro Expand → Type Checker → Codegen → go build → Binary
+                                                      → Interpreter (REPL)
+```
+
+## Documentation
+
+- [`docs/language-design.md`](docs/language-design.md) — syntax, type system, grammar, backend strategy, design decisions
+- [`docs/compiler-architecture.md`](docs/compiler-architecture.md) — pipeline, file structure, phase contracts, testing strategy
+- [`docs/dependency-management.md`](docs/dependency-management.md) — `vex.mod` manifest, `vex get`, global cache, Go module integration
+- [`docs/mvp.md`](docs/mvp.md) — MVP definition and success criteria
 
 ## Development