diff --git a/AI_FIRST.md b/AI_FIRST.md
deleted file mode 100644
index cb72648..0000000
--- a/AI_FIRST.md
+++ /dev/null
@@ -1,194 +0,0 @@
-# AI-First Clojure/Nim
-
-## Философия
-
-Този проект не е за човешки програмисти с Emacs/VS Code. Този проект е за **AI агенти**, които работят през терминал.
-
-### Защо AI-First?
-
-- AI не може да клика в GUI. AI работи с текст, команди и структурирани данни.
-- AI не се нуждае от syntax highlighting. AI се нуждае от **структуриран изход**.
-- AI не иска REPL с цветни prompt-ове. AI иска **EDN/JSON отговори** с метаданни.
-- AI commit-ва кода автоматично. Нуждаем се от **git-aware REPL**.
-
-## Архитектура на AI REPL
-
-```
-┌─────────────┐      EDN/JSON      ┌─────────────────┐
-│   AI Agent  │ ◄────────────────► │   cljnim repl   │
-│  (терминал) │   structured I/O   │  (structured)   │
-└─────────────┘                    └────────┬────────┘
-                                            │
-                                     ┌──────▼──────┐
-                                     │  Compiler   │
-                                     │   + Eval    │
-                                     └──────┬──────┘
-                                            │
-                                     ┌──────▼──────┐
-                                     │   Git Ops   │
-                                     │  (вградени) │
-                                     └─────────────┘
-```
-
-## Принципи
-
-### 1. Структуриран I/O
-
-Всеки вход и изход е структуриран:
-
-```edn
-;; AI изпраща:
-{:op :eval
- :form "(+ 1 2 3)"
- :ns "user"
- :request-id "uuid-1234"}
-
-;; REPL връща:
-{:status :ok
- :request-id "uuid-1234"
- :result {:type :int
-          :value 6
-          :printed "6"}
- :meta {:ms 0.003
-        :form "(+ 1 2 3)"
-        :ns "user"}}
-
-;; Грешка:
-{:status :error
- :request-id "uuid-1234"
- :error {:type :compiler/unknown-symbol
-         :symbol "unknwon-fn"
-         :line 1
-         :column 5
-         :message "Unknown symbol: unknwon-fn"
-         :trace []}}
-```
-
-### 2. Batch Evaluation
-
-AI може да изпрати множество форми наведнъж:
-
-```edn
-{:op :eval-batch
- :forms ["(defn add [a b] (+ a b))"
-         "(add 10 20)"
-         "(def data {:x 1 :y 2})"]
- :mode :compile}
-```
-
-### 3. Git-Aware REPL
-
-Вградени git операции без напускане на REPL:
-
-```clojure
-;; Clojure форми, които управляват git:
-(git/status)
-;; => {:branch "main" :untracked ["src/new.clj"] :modified []}
-
-(git/diff)
-;; => {:files [{:path "src/core.clj" :added 5 :removed 2}]}
-
-(git/commit "Add factorial" {:push true})
-;; => {:sha "a1b2c3d" :pushed true}
-```
-
-### 4. Self-Describing Система
-
-AI винаги може да попита системата какво може:
-
-```clojure
-(apropos "map")
-;; => [{:name "map" :ns "clojure.core" :type :function}
-;;     {:name "map?" :ns "clojure.core" :type :function}
-;;     {:name "mapv" :ns "clojure.core" :type :function}]
-
-(doc map)
-;; => {:name "map"
-;;     :ns "clojure.core"
-;;     :doc "Returns a lazy sequence..."
-;;     :args [["f" "coll"] ["f" "c1" "c2" "& colls"]]
-;;     :source "(defn map [f coll] ...)"}
-```
-
-### 5. File Operations през REPL
-
-AI не отваря редактор. AI манипулира файлове през Clojure:
-
-```clojure
-(file/read "src/core.clj")
-;; => "(ns core)..."
-
-(file/write "src/new.clj" "(ns new)")
-;; => {:bytes-written 8 :path "src/new.clj"}
-
-(file/ls "src")
-;; => ["types.nim" "reader.nim" "emitter.nim"]
-```
-
-### 6. Tool-Call Формат
-
-REPL може да работи в `tool-call` режим за директна интеграция с AI frameworks:
-
-```json
-{
-  "tool": "cljnim/eval",
-  "arguments": {
-    "code": "(defn fib [n] (if (< n 2) n (+ (fib (- n 1)) (fib (- n 2)))))",
-    "mode": "compile"
-  }
-}
-```
-
-## Режими на REPL
-
-### Човешки режим (default)
-```
-cljnim> (+ 1 2)
-3
-cljnim> (defn square [x] (* x x))
-#'user/square
-```
-
-### AI режим (`--ai` или `--json`)
-```bash
-$ cljnim repl --json
-{"status":"ready","ns":"user"}
-> (defn add [a b] (+ a b))
-{"status":"ok","result":{"type":"var","name":"add","ns":"user"}}
-> (add 10 20)
-{"status":"ok","result":{"type":"int","value":30,"printed":"30"},"meta":{"ms":0.001}}
-```
-
-### Batch режим
-```bash
-$ cljnim run-batch script.clj --format json
-[{"form":"(defn f [x] x)","status":"ok","result":"#'user/f"}
- {"form":"(f 42)","status":"ok","result":{"type":"int","value":42}}]
-```
-
-## Интеграция с AI Workflow
-
-```bash
-# 1. AI клонира репото
-git clone git@gitlab.com:balvatar/lisp-nim.git
-cd lisp-nim
-
-# 2. AI стартира REPL в JSON режим
-cljnim repl --json
-
-# 3. AI изпраща форми, получава структурирани отговори
-# 4. AI пише файлове през (file/write ...)
-# 5. AI commit-ва през (git/commit ...)
-# 6. AI push-ва през (git/push)
-```
-
-## Защо това е бъдещето?
-
-| Аспект | Човешки IDE | AI Terminal |
-|---|---|---|
-| Интерфейс | GUI + мишка | Текст + команды |
-| Навигация | Кликване | `(apropos ...)`, `(doc ...)` |
-| Рефакториране | Ръчно | Batch eval + git diff |
-| Тестване | Run button | `(run-tests)` структуриран отговор |
-| Commit | GUI диалог | `(git/commit "msg")` |
-| Context | Отворени файлове | REPL ns + `:context` |
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
deleted file mode 100644
index a340891..0000000
--- a/ARCHITECTURE.md
+++ /dev/null
@@ -1,169 +0,0 @@
-# Архитектура: Истински Clojure върху Nim
-
-## Философия
-
-Това не е "Clojure-подобен" език. Това е **Clojure диалект**, който компилира към Nim.
-Макросите, структурите от данни и семантиката са съвместими с Clojure (JVM).
-
-### Защо истински Clojure?
-
-| Аспект | Clojure-inspired Lisp | Истински Clojure диалект |
-|---|---|---|
-| **Библиотеки** | Пишеш всичко на ново | Можеш да пренесеш `clojure.core`, `clojure.string`, `clojure.set` |
-| **Разработчици** | Учат нов език | Всеки Clojure програмист може да го ползва веднага |
-| **Инструменти** | Собствени | Работи с `clojure-mode`, CIDER, Calva (с някои адаптации) |
-| **Финтех/Indустрия** | Не е опция | Може да се ползва за реални проекти |
-
-### Който го е правил успешно
-
-- **ClojureScript** — компилира Clojure до JS. Използва Google Closure. Пълна съвместимост.
-- **Babashka** — GraalVM native image на Clojure. Бърз старт, скриптове, портативен.
-- **Ferret** — Clojure → C++11 за embedded системи. Работи на 2KB RAM.
-- **ClojErl** — Clojure върху BEAM. Жертва част от performance заради семантиката.
-
-## Архитектура на Компилатора
-
-```
-┌─────────────────┐
-│   .clj Файл     │  ← Стандартен Clojure код
-└────────┬────────┘
-         │
-    ┌────▼────┐
-    │ Reader  │  ← EDN парсер, Clojure symbols, quoted forms
-    └────┬────┘
-         │
-    ┌────▼────┐
-    │ Macro   │  ← defmacro, syntax-quote, unquote, unquote-splicing
-    │ Expansion│   (работи върху Clojure структури)
-    └────┬────┘
-         │
-    ┌────▼────┐
-    │ Analyzer│  ← Специални форми, locals, recur targets,
-    │         │   closures, type hints
-    └────┬────┘
-         │
-    ┌────▼────┐
-    │ Emitter │  ← Генерира Nim AST (не Nim текст!)
-    │ (Nim)   │   Използва Nim макроси за компилация
-    └────┬────┘
-         │
-    ┌────▼────┐
-    │  Nim    │  ← C код, после машинен код
-    │Compiler │   оптимизация, tree-shaking, LTO
-    └────┬────┘
-         │
-    ┌────▼────┐
-    │ Бинарен │  ← Единичен файл, < 10MB, бърз старт
-    │ Файл    │
-    └─────────┘
-```
-
-## Ключови Решения
-
-### 1. Компилатор, не Интерпретатор
-
-Изборът е **AOT компилатор**, подобно на ClojureScript. Няма да пишем интерпретатор в Nim.
-
-- **Предимство:** Бърз runtime, малък footprint, компилира до C.
-- **Недостатък:** REPL е по-труден (но не невъзможен — виж ClojureScript self-hosted).
-- **Урок от calcit-runner:** Те започнаха с интерпретатор в Nim и се провалиха. Ние директно компилираме.
-
-### 2. Clojure Макроси на Clojure Структури
-
-```clojure
-;; Това трябва да работи без промяна:
-(defmacro unless [condition & body]
-  `(if (not ~condition)
-     (do ~@body)))
-
-(unless false
-  (println "Работи!"))
-```
-
-Макросите се разширяват **преди** да стигнем до Nim. Nim никога не вижда Clojure макрос.
-
-### 3. Persistent Структури от Данни в Nim
-
-Clojure's Hash Array Mapped Trie (HAMT) трябва да се имплементира в Nim:
-
-```nim
-# Nim runtime за Clojure Vector
-type
-  NodeKind = enum nkLeaf, nkInternal
-  Node[T] = ref object
-    case kind: NodeKind
-    of nkLeaf: values: seq[T]
-    of nkInternal: children: array[32, Node[T]]
-  
-  PersistentVector[T] = object
-    root: Node[T]
-    tail: seq[T]
-    count: int
-```
-
-- `conj`, `assoc`, `dissoc` — O(log₃₂ n)
-- `nth`, `get` — O(log₃₂ n)
-- `count` — O(1)
-
-### 4. Nim Interop (вместо Java Interop)
-
-Тъй като нямаме JVM, interop-ът е с Nim:
-
-```clojure
-;; Извикване на Nim функция
-(nim/strutils.join ", " ["a" "b" "c"])
-
-;; Достъп до Nim тип
-(nim/times.DateTime)
-
-;; FFI към C библиотека
-(nim/ffi.import "math.h" :functions [["sin" :double [:double]]])
-```
-
-### 5. Симулация на Clojure Runtime
-
-| Clojure JVM | Нашата Имплементация |
-|---|---|
-| `Var` | Глобални Nim променливи с atomic CAS |
-| `Namespace` | Nim модул + хеш таблица със символи |
-| `Atom` | `ref` тип с compare-and-swap |
-| `Agent` | Channel + Worker thread |
-| `Ref/STM` | Software transactional memory в Nim |
-| `Multimethod` | Диспач таблица + `isa?` проверка |
-| `Protocol` | Nim concepts + dispatch таблица |
-
-## Фази с Индустриален Фокус
-
-### Phase 1: Компилатор (не REPL!)
-Фокус: AOT компилация на прости Clojure файлове към Nim.
-
-### Phase 2: Core Библиотека
-Фокус: Пренасяне на `clojure.core` функции. Тестове с реални Clojure тестове.
-
-### Phase 3: Nim Interop + FFI
-Фокус: Извикване на Nim/C библиотеки. Това е нашето "убийствено" предимство.
-
-### Phase 4: REPL (Self-hosted)
-Фокус: REPL като ClojureScript (компилира в паметта).
-
-### Phase 5: Инструменти
-Фокус: nREPL съвместимост, LSP, пакетен мениджър (Nimble интеграция).
-
-## Изисквания за Съвместимост
-
-- `clojure.core` namespace трябва да е наличен
-- `defn`, `let`, `if`, `do`, `recur`, `loop` — точна семантика
-- `->`, `->>`, `cond->` — макроси
-- Persistent Vector, Map, Set — стандартни операции
-- Keywords (`:name`) и Symbols (`'sym`) — interned
-
-## Разлики от JVM Clojure (приемливи)
-
-| JVM Clojure | Clojure/Nim |
-|---|---|
-| Java interop | Nim interop |
-| JVM threads | Nim threads (no GIL!) |
-| Dynamic classloading | AOT компилация |
-| `gen-class` | `gen-nim` (генериране на Nim типове) |
-| Reflection | Compile-time метаданни |
-| Big ecosystem | Достъп до Nim + C ecosystem |
diff --git a/README.md b/README.md
index cd5b544..659a594 100644
--- a/README.md
+++ b/README.md
@@ -1,114 +1,197 @@
 # Clojure/Nim
 
-> Реализация на Clojure върху Nim-lang
+> A Clojure dialect that compiles to Nim, then to C, then to native binaries.
 
-## Какво е това?
+## What is this?
 
-Clojure/Nim е проект, целящ да предостави Clojure език и runtime върху Nim. Вдъхновен е от ClojureScript и Babashka, но вместо JavaScript или JVM, целта е компилация към Nim код и използване на Nim runtime.
+Clojure/Nim is an **AI-first** implementation of the Clojure language targeting the Nim ecosystem. Instead of running on the JVM or JavaScript, it compiles Clojure code directly to Nim source, which then compiles to C and finally to a native binary.
 
-## Защо?
+### Why?
 
-- **Единен AST**: Nim предлага мощна макро система и AST манипулация
-- **Производителност**: Компилиран към C, Nim дава C-подобна скорост с Lisp-удобство
-- **Размер**: Минимален runtime footprint в сравнение с JVM
-- **Метапрограмиране**: Съчетание на Clojure макроси и Nim макроси
+- **Native Performance**: Compiles to C via Nim. No JVM warmup, no GC pauses.
+- **Tiny Binaries**: Single-file executables, often under 1MB.
+- **Nim Ecosystem**: Direct access to Nim and C libraries via FFI.
+- **AI-Native**: Built for AI agents working in terminals — structured JSON REPL, batch evaluation, git integration.
 
-## Архитектура
-
-```
-Clojure Изходен Код (.clj)
-         ↓
-    Clojure Reader (Clojure → Clojure Data)
-         ↓
-    Макро Разширение (Clojure Macros)
-         ↓
-    AST Транслатор (Clojure AST → Nim AST)
-         ↓
-    Nim Компилатор
-         ↓
-    C Код → Машинен Код
-```
-
-## Статус
-
-> ⚠️ **Ранен етап** — Проектът е във фаза на планиране и базова имплементация.
-
-Виж [ROADMAP.md](ROADMAP.md) за текущия прогрес.
-
-## Бърз Старт
+## Quick Start
 
 ```bash
-# Клониране
-git clone <repo-url>
-cd clojure-nim
+# Clone
+git clone https://gitlab.com/balvatar/lisp-nim.git
+cd lisp-nim
 
-# Изграждане
+# Build
 make build
 
-# REPL
-./cljnim
-
-# Изпълнение на файл
+# Run a file
 ./cljnim run examples/hello.clj
+
+# Start human REPL
+./cljnim repl
+
+# Start AI REPL (JSON mode)
+./cljnim repl --json
 ```
 
-## Примери
+## Examples
 
+### Hello World
 ```clojure
-;; hello.clj
-(ns hello)
+;; examples/hello.clj
+(println "Hello, Nim world!")
+(println (+ 1 2 3))
+```
 
-(println "Здравей, Nim свят!")
+```bash
+$ ./cljnim run examples/hello.clj
+Hello, Nim world!
+6
+```
 
-(defn факториел [n]
-  (if (<= n 1)
+### Functions & Recursion
+```clojure
+;; examples/math.clj
+(defn square [x]
+  (* x x))
+
+(defn factorial [n]
+  (if (= n 0)
     1
-    (* n (факториел (- n 1)))))
+    (* n (factorial (- n 1)))))
 
-(println "5! =" (факториел 5))
+(let [a 5]
+  (println (square a))
+  (println (factorial a)))
 ```
 
-```clojure
-;; Работа със структури от данни
-(def данни
-  {:име "Иван"
-   :възраст 30
-   :езици ["Clojure" "Nim" "C"]})
-
-(println (get-in данни [:езици 0]))
-;; => "Clojure"
+```bash
+$ ./cljnim run examples/math.clj
+25
+120
 ```
 
-## Структура на Проекта
+## AI-First REPL
+
+Clojure/Nim is built for AI agents. The JSON REPL provides structured I/O perfect for programmatic interaction.
+
+```bash
+$ ./cljnim repl --json
+{"status":"ready","ns":"user","mode":"json"}
+
+> {"op":"eval","form":"(+ 1 2 3)"}
+{"status":"ok","result":{"printed":"6"},"meta":{"ms":861}}
+
+> {"op":"eval","form":"(defn square [x] (* x x))"}
+{"status":"ok","result":{"type":"var","name":"square"}}
+
+> {"op":"eval","form":"(square 5)"}
+{"status":"ok","result":{"printed":"25"}}
+
+> {"op":"quit"}
+{"status":"ok","bye":true}
+```
+
+### Supported REPL Operations
+
+| Operation | Description |
+|---|---|
+| `eval` | Evaluate a single Clojure form |
+| `eval-batch` | Evaluate multiple forms at once |
+| `get-defs` | List all defined vars in current session |
+| `clear` | Clear all session definitions |
+| `quit` | Exit the REPL |
+
+See [`docs/AI_FIRST.md`](docs/AI_FIRST.md) for the full AI integration design.
+
+## Architecture
+
+```
+Clojure Source (.clj)
+       ↓
+   Reader (EDN parser)
+       ↓
+   Macro Expansion (Clojure macros)
+       ↓
+   Analyzer (special forms, locals)
+       ↓
+   Emitter (Clojure AST → Nim AST)
+       ↓
+   Nim Compiler → C Code
+       ↓
+   C Compiler → Native Binary
+```
+
+See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for details.
+
+## Project Structure
 
 ```
 ├── src/
-│   ├── reader/         # Clojure reader (EDN парсер)
-│   ├── analyzer/       # Semantic анализатор
-│   ├── macros/         # Core macros (defn, let, if, и т.н.)
-│   ├── emitter/        # Генератор на Nim код
-│   ├── runtime/        # Clojure runtime в Nim
-│   └── repl/           # Интерактивна обвивка
+│   ├── cljnim.nim       # CLI entry point
+│   ├── reader.nim       # Clojure reader / EDN parser
+│   ├── emitter.nim      # Nim code generator
+│   ├── repl.nim         # Human & AI REPL
+│   ├── types.nim        # Clojure value types
+│   ├── macros.nim       # Macro expansion engine
+│   └── runtime.nim      # Runtime implementation
 ├── lib/
-│   └── core.clj        # Clojure core библиотека
-├── tests/              # Тестове
-├── examples/           # Примери
+│   └── cljnim_runtime.nim   # Clojure runtime in Nim
+├── examples/
+│   ├── hello.clj
+│   └── math.clj
+├── docs/                    # Documentation (EN + BG)
+├── tests/
 ├── Makefile
-└── README.md
+└── cljnim.nimble
 ```
 
-## Изисквания
+## Supported Features
+
+### Working Now ✅
+- Reader: numbers, strings, symbols, keywords, lists `()`, vectors `[]`
+- Special forms: `def`, `defn`, `fn`, `let`, `if`, `do`, `quote`
+- Arithmetic: `+`, `-`, `*`, `/`, `=`, `<`, `>`
+- Functions: `println`
+- Human REPL and JSON REPL
+- AOT compilation to native binaries
+
+### In Progress 🔄
+- Persistent data structures (Vector, Map, Set)
+- `defmacro` system
+- Nim/C interop
+- File operations from REPL
+- Git operations from REPL
+
+See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the full roadmap.
+
+## Requirements
 
 - Nim >= 2.0
-- GCC или Clang
+- GCC or Clang
 - make
 
-## Лиценз
+## Documentation
 
-MIT License — виж [LICENSE](LICENSE).
+| Document | Description |
+|---|---|
+| [`docs/README.bg.md`](docs/README.bg.md) | Българско README |
+| [`docs/GUIDE.md`](docs/GUIDE.md) | User guide (English) |
+| [`docs/GUIDE.bg.md`](docs/GUIDE.bg.md) | Ръководство за потребителя |
+| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Architecture & design |
+| [`docs/ARCHITECTURE.bg.md`](docs/ARCHITECTURE.bg.md) | Архитектура и дизайн |
+| [`docs/AI_FIRST.md`](docs/AI_FIRST.md) | AI-first design philosophy |
+| [`docs/AI_FIRST.bg.md`](docs/AI_FIRST.bg.md) | AI-first философия |
+| [`docs/API.md`](docs/API.md) | REPL API reference |
+| [`docs/API.bg.md`](docs/API.bg.md) | REPL API референция |
+| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Development roadmap |
+| [`docs/ROADMAP.bg.md`](docs/ROADMAP.bg.md) | Пътна карта |
 
-## Благодарности
+## License
 
-- [Clojure](https://clojure.org/) — Rich Hickey и екипът
-- [Nim](https://nim-lang.org/) — Andreas Rumpf и общността
-- Вдъхновено от ClojureScript, Babashka и Clojerl
+MIT License — see [LICENSE](LICENSE).
+
+## Acknowledgments
+
+- [Clojure](https://clojure.org/) — Rich Hickey and team
+- [Nim](https://nim-lang.org/) — Andreas Rumpf and community
+- Inspired by ClojureScript, Babashka, Ferret, and Pixie
diff --git a/ROADMAP.md b/ROADMAP.md
deleted file mode 100644
index c5f13fb..0000000
--- a/ROADMAP.md
+++ /dev/null
@@ -1,108 +0,0 @@
-# Пътна Карта: Clojure/Nim (AI-First Edition)
-
-## Фаза 0: Компилаторно Ядро ✅
-
-- [x] Clojure Reader (EDN парсер)
-- [x] AST → Nim Emitter
-- [x] CLI (`compile`, `run`, `read`)
-- [x] Специални форми: `def`, `defn`, `fn`, `let`, `if`, `do`, `quote`
-- [x] Оператори: `+`, `-`, `*`, `/`, `=`, `<`, `>`
-- [x] Функции: `println` → `echo`
-- [x] Примери: `hello.clj`, `math.clj` (факториел)
-
-## Фаза 1: AI-First REPL 🔄
-
-**Цел:** REPL, който AI може да ползва през терминал без редактор.
-
-### 1.1 Структуриран REPL
-- [ ] JSON/EDN режим (`cljnim repl --json`)
-- [ ] Batch evaluation (`cljnim run-batch script.clj --format json`)
-- [ ] Структурирани грешки (line, column, type, message, trace)
-- [ ] Метаданни в отговора (ms, ns, form, type)
-
-### 1.2 Self-Describing Система
-- [ ] `(doc fn)` — връща структурирани метаданни
-- [ ] `(apropos "str")` — търсене на функции
-- [ ] `(source fn)` — изходен код на функция
-- [ ] `(ns-publics 'clojure.core)` — листване на публични символи
-
-### 1.3 File Operations
-- [ ] `(file/read "path")` — четене на файл
-- [ ] `(file/write "path" "content")` — запис на файл
-- [ ] `(file/append "path" "content")` — добавяне
-- [ ] `(file/ls "dir")` — листване на директория
-- [ ] `(file/exists? "path")` — проверка
-
-### 1.4 Git Operations (вградени)
-- [ ] `(git/status)` — текущ статус
-- [ ] `(git/diff)` — разлики
-- [ ] `(git/add "file")` — stage
-- [ ] `(git/commit "msg")` — commit
-- [ ] `(git/push)` — push
-- [ ] `(git/log)` — история
-
-## Фаза 2: Persistent Структури от Данни
-
-**Цел:** Истински Clojure immutable структури.
-
-- [ ] **Persistent Vector** (Hash Array Mapped Trie)
-- [ ] **Persistent Map** (HAMT)
-- [ ] **Persistent Set**
-- [ ] `conj`, `assoc`, `dissoc`, `get`, `get-in`
-- [ ] `nth`, `first`, `rest`, `last`, `count`
-
-## Фаза 3: Clojure Core Библиотека
-
-**Цел:** Достатъчно функции за реални скриптове.
-
-### 3.1 Seq функции
-- [ ] `map`, `filter`, `reduce`
-- [ ] `take`, `drop`, `partition`
-- [ ] `concat`, `interleave`
-- [ ] `range`
-
-### 3.2 Низове и IO
-- [ ] `str`, `pr-str`, `println`, `prn`
-- [ ] `slurp`, `spit`
-- [ ] `read-line`
-
-### 3.3 Мета
-- [ ] `meta`, `with-meta`, `vary-meta`
-- [ ] `type`, `instance?`
-
-## Фаза 4: Макро Система
-
-**Цел:** `defmacro` да работи.
-
-- [ ] `macroexpand`, `macroexpand-1`
-- [ ] `syntax-quote`, `unquote`, `unquote-splicing`
-- [ ] `gensym`
-- [ ] Core макроси: `->`, `->>`, `and`, `or`, `when`, `cond`
-
-## Фаза 5: Nim Interop
-
-**Цел:** Достъп до целия Nim ecosystem.
-
-- [ ] `(nim/import "strutils")` — import на Nim модул
-- [ ] `(nim/ffi "math.h" :functions [["sin" :double [:double]]])` — C FFI
-- [ ] `(nim/call "strutils.join" ", " ["a" "b"])` — извикване
-
-## Фаза 6: AOT Компилация + REPL
-
-**Цел:** Бързо стартиране на скриптове.
-
-- [ ] AOT компилация на цели проекти
-- [ ] Кеширане на компилирани модули
-- [ ] REPL в self-hosted режим (като ClojureScript)
-
-## Фаза 7: Многонишковост
-
-- [ ] **Atoms** (CAS)
-- [ ] **Agents**
-- [ ] **core.async** channels (упростен вариант)
-
-## Текущ Фокус
-
-**Фаза 1 — AI-First REPL**
-
-Следваща задача: `cljnim repl --json` с batch evaluation и структурирани отговори.
diff --git a/docs/AI_FIRST.bg.md b/docs/AI_FIRST.bg.md
new file mode 100644
index 0000000..1b0dc23
--- /dev/null
+++ b/docs/AI_FIRST.bg.md
@@ -0,0 +1,107 @@
+# AI-First Философия на Дизайна
+
+## Защо AI-First?
+
+Съвременната софтуерна разработка се извършва все повече от **AI агенти**, работещи в терминални среди. Тези агенти не използват GUI, IDE или syntax highlighting. Те се нуждаят от:
+
+1. **Структуриран I/O** — JSON/EDN, не просто текст
+2. **Програмно Управление** — Всяка операция трябва да е скриптваема
+3. **Самоописващи Се Системи** — AI може да открива възможности по време на изпълнение
+4. **Git Интеграция** — Контрол на версиите като част от работния процес
+
+## Принципи
+
+### 1. Структуриран I/O
+
+Цялата REPL комуникация използва JSON:
+
+```json
+// Вход
+{"op": "eval", "form": "(+ 1 2)", "request-id": "uuid"}
+
+// Изход
+{
+  "status": "ok",
+  "request-id": "uuid",
+  "result": {"type": "int", "value": 3, "printed": "3"},
+  "meta": {"ms": 0.5, "ns": "user"}
+}
+```
+
+### 2. Batch Операции
+
+AI агентите оценяват множество форми наведнъж:
+
+```json
+{"op": "eval-batch",
+ "forms": [
+   "(defn add [a b] (+ a b))",
+   "(add 10 20)"
+ ]}
+```
+
+### 3. Персистентност на Сесията
+
+Дефинициите се запазват в рамките на REPL сесия, позволявайки инкрементална разработка:
+
+```json
+{"op": "eval", "form": "(defn square [x] (* x x))"}
+{"op": "eval", "form": "(square 5)"}
+{"op": "get-defs"}
+```
+
+### 4. Възстановяване от Грешки
+
+Всички грешки са структурирани с тип, съобщение и контекст:
+
+```json
+{
+  "status": "error",
+  "error": {
+    "type": "compiler/unknown-symbol",
+    "symbol": "unknwon-fn",
+    "message": "Unknown symbol: unknwon-fn",
+    "form": "(unknwon-fn 1 2)"
+  }
+}
+```
+
+## AI Работен Процес
+
+```bash
+# 1. Клониране на репото
+git clone git@gitlab.com:balvatar/lisp-nim.git
+cd lisp-nim
+
+# 2. Стартиране на AI REPL
+cljnim repl --json
+
+# 3. AI оценява форми, получава структурирани отговори
+# 4. AI пише файлове през (file/write ...) [бъдеще]
+# 5. AI commit-ва през (git/commit ...) [бъдеще]
+# 6. AI push-ва през (git/push) [бъдеще]
+```
+
+## Сравнение
+
+| Аспект | Човешки IDE | AI Терминал |
+|---|---|---|
+| Интерфейс | GUI + мишка | Текст + команди |
+| Навигация | Кликване | `(apropos ...)`, `(doc ...)` |
+| Рефакториране | Ръчно | Batch eval + git diff |
+| Тестване | Run button | `(run-tests)` структуриран отговор |
+| Commit | GUI диалог | `(git/commit "msg")` |
+
+## Бъдеще: Tool-Call Формат
+
+Директна интеграция с AI frameworks:
+
+```json
+{
+  "tool": "cljnim/eval",
+  "arguments": {
+    "code": "(defn fib [n] ...)",
+    "mode": "compile"
+  }
+}
+```
diff --git a/docs/AI_FIRST.md b/docs/AI_FIRST.md
new file mode 100644
index 0000000..19fb527
--- /dev/null
+++ b/docs/AI_FIRST.md
@@ -0,0 +1,107 @@
+# AI-First Design Philosophy
+
+## Why AI-First?
+
+Modern software development is increasingly done by **AI agents** operating in terminal environments. These agents do not use GUIs, IDEs, or syntax highlighting. They need:
+
+1. **Structured I/O** — JSON/EDN, not plain text
+2. **Programmatic Control** — Every operation must be scriptable
+3. **Self-Describing Systems** — AI can discover capabilities at runtime
+4. **Git Integration** — Version control as part of the workflow
+
+## Principles
+
+### 1. Structured I/O
+
+All REPL communication uses JSON:
+
+```json
+// Input
+{"op": "eval", "form": "(+ 1 2)", "request-id": "uuid"}
+
+// Output
+{
+  "status": "ok",
+  "request-id": "uuid",
+  "result": {"type": "int", "value": 3, "printed": "3"},
+  "meta": {"ms": 0.5, "ns": "user"}
+}
+```
+
+### 2. Batch Operations
+
+AI agents evaluate multiple forms at once:
+
+```json
+{"op": "eval-batch",
+ "forms": [
+   "(defn add [a b] (+ a b))",
+   "(add 10 20)"
+ ]}
+```
+
+### 3. Session Persistence
+
+Definitions persist within a REPL session, allowing incremental development:
+
+```json
+{"op": "eval", "form": "(defn square [x] (* x x))"}
+{"op": "eval", "form": "(square 5)"}
+{"op": "get-defs"}
+```
+
+### 4. Error Recovery
+
+All errors are structured with type, message, and context:
+
+```json
+{
+  "status": "error",
+  "error": {
+    "type": "compiler/unknown-symbol",
+    "symbol": "unknwon-fn",
+    "message": "Unknown symbol: unknwon-fn",
+    "form": "(unknwon-fn 1 2)"
+  }
+}
+```
+
+## AI Workflow
+
+```bash
+# 1. Clone repo
+git clone git@gitlab.com:balvatar/lisp-nim.git
+cd lisp-nim
+
+# 2. Start AI REPL
+cljnim repl --json
+
+# 3. AI evaluates forms, gets structured responses
+# 4. AI writes files via (file/write ...) [future]
+# 5. AI commits via (git/commit ...) [future]
+# 6. AI pushes via (git/push) [future]
+```
+
+## Comparison
+
+| Aspect | Human IDE | AI Terminal |
+|---|---|---|
+| Interface | GUI + mouse | Text + commands |
+| Navigation | Clicking | `(apropos ...)`, `(doc ...)` |
+| Refactoring | Manual | Batch eval + git diff |
+| Testing | Run button | `(run-tests)` structured response |
+| Commit | GUI dialog | `(git/commit "msg")` |
+
+## Future: Tool-Call Format
+
+Direct integration with AI frameworks:
+
+```json
+{
+  "tool": "cljnim/eval",
+  "arguments": {
+    "code": "(defn fib [n] ...)",
+    "mode": "compile"
+  }
+}
+```
diff --git a/docs/API.bg.md b/docs/API.bg.md
new file mode 100644
index 0000000..a5ac7d4
--- /dev/null
+++ b/docs/API.bg.md
@@ -0,0 +1,155 @@
+# REPL API Референция
+
+## JSON REPL Протокол
+
+Стартирайте JSON REPL:
+```bash
+cljnim repl --json
+```
+
+REPL чете по един JSON обект на ред и отговаря с по един JSON обект на ред.
+
+## Операции
+
+### `eval`
+Оценява единична Clojure форма.
+
+**Заявка:**
+```json
+{"op": "eval", "form": "(+ 1 2 3)"}
+```
+
+**Отговор (успех):**
+```json
+{
+  "status": "ok",
+  "result": {
+    "type": "unknown",
+    "value": "6",
+    "printed": "6"
+  },
+  "meta": {
+    "ns": "user",
+    "ms": 861.5,
+    "form": "(+ 1 2 3)"
+  }
+}
+```
+
+**Отговор (грешка):**
+```json
+{
+  "status": "error",
+  "error": {
+    "type": "reader/error",
+    "message": "Unterminated list",
+    "form": "( + 1 2"
+  },
+  "meta": {
+    "ns": "user",
+    "ms": 0.1
+  }
+}
+```
+
+**Незадължителни полета:**
+- `request-id` — Correlation ID, върнат в отговора
+- `ns` — Целево namespace (по подразбиране: `"user"`)
+
+---
+
+### `eval-batch`
+Оценява множество форми последователно.
+
+**Заявка:**
+```json
+{"op": "eval-batch", "forms": ["(defn f [x] x)", "(f 42)"]}
+```
+
+**Отговор:**
+```json
+{
+  "status": "ok",
+  "results": [
+    {"status": "ok", "result": {"type": "var", "name": "f", ...}},
+    {"status": "ok", "result": {"printed": "42"}, ...}
+  ]
+}
+```
+
+---
+
+### `get-defs`
+Листва всички дефинирани променливи в текущата сесия.
+
+**Заявка:**
+```json
+{"op": "get-defs"}
+```
+
+**Отговор:**
+```json
+{"status": "ok", "defs": ["add", "square"], "ns": "user"}
+```
+
+---
+
+### `clear`
+Изчиства всички дефиниции от сесията.
+
+**Заявка:**
+```json
+{"op": "clear"}
+```
+
+**Отговор:**
+```json
+{"status": "ok", "cleared": true}
+```
+
+---
+
+### `quit`
+Излиза от REPL.
+
+**Заявка:**
+```json
+{"op": "quit"}
+```
+
+**Отговор:**
+```json
+{"status": "ok", "bye": true}
+```
+
+## Схема на Отговора
+
+Всички отговори съдържат:
+- `status` — `"ok"` или `"error"`
+
+При успех:
+- `result` — Обект с резултат от оценката
+  - `type` — `"var"`, `"unknown"`, и т.н.
+  - `printed` — Текстово представяне на резултата
+- `meta` — Метаданни
+  - `ns` — Текущо namespace
+  - `ms` — Време за изпълнение в милисекунди
+  - `form` — Оригиналната форма (ако е `eval`)
+
+При грешка:
+- `error` — Обект с грешка
+  - `type` — Категория на грешката
+  - `message` — Четимо съобщение
+- `meta` — Както при успех
+
+## Команди в Човешки REPL
+
+В човешки режим (`cljnim repl`):
+
+| Команда | Описание |
+|---|---|
+| `:quit`, `:q` | Изход от REPL |
+| `:help`, `:h` | Показване на помощ |
+| `:defs` | Листване на дефинирани променливи |
+| `:clear` | Изчистване на дефинициите |
+| `:ns` | Показване на текущото namespace |
diff --git a/docs/API.md b/docs/API.md
new file mode 100644
index 0000000..7aaf787
--- /dev/null
+++ b/docs/API.md
@@ -0,0 +1,155 @@
+# REPL API Reference
+
+## JSON REPL Protocol
+
+Start the JSON REPL:
+```bash
+cljnim repl --json
+```
+
+The REPL reads one JSON object per line and responds with one JSON object per line.
+
+## Operations
+
+### `eval`
+Evaluate a single Clojure form.
+
+**Request:**
+```json
+{"op": "eval", "form": "(+ 1 2 3)"}
+```
+
+**Response (success):**
+```json
+{
+  "status": "ok",
+  "result": {
+    "type": "unknown",
+    "value": "6",
+    "printed": "6"
+  },
+  "meta": {
+    "ns": "user",
+    "ms": 861.5,
+    "form": "(+ 1 2 3)"
+  }
+}
+```
+
+**Response (error):**
+```json
+{
+  "status": "error",
+  "error": {
+    "type": "reader/error",
+    "message": "Unterminated list",
+    "form": "( + 1 2"
+  },
+  "meta": {
+    "ns": "user",
+    "ms": 0.1
+  }
+}
+```
+
+**Optional fields:**
+- `request-id` — Correlation ID, echoed in the response
+- `ns` — Target namespace (default: `"user"`)
+
+---
+
+### `eval-batch`
+Evaluate multiple forms in sequence.
+
+**Request:**
+```json
+{"op": "eval-batch", "forms": ["(defn f [x] x)", "(f 42)"]}
+```
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "results": [
+    {"status": "ok", "result": {"type": "var", "name": "f", ...}},
+    {"status": "ok", "result": {"printed": "42"}, ...}
+  ]
+}
+```
+
+---
+
+### `get-defs`
+List all vars defined in the current session.
+
+**Request:**
+```json
+{"op": "get-defs"}
+```
+
+**Response:**
+```json
+{"status": "ok", "defs": ["add", "square"], "ns": "user"}
+```
+
+---
+
+### `clear`
+Clear all session definitions.
+
+**Request:**
+```json
+{"op": "clear"}
+```
+
+**Response:**
+```json
+{"status": "ok", "cleared": true}
+```
+
+---
+
+### `quit`
+Exit the REPL.
+
+**Request:**
+```json
+{"op": "quit"}
+```
+
+**Response:**
+```json
+{"status": "ok", "bye": true}
+```
+
+## Response Schema
+
+All responses contain:
+- `status` — `"ok"` or `"error"`
+
+On success:
+- `result` — Evaluation result object
+  - `type` — `"var"`, `"unknown"`, etc.
+  - `printed` — String representation of the result
+- `meta` — Metadata
+  - `ns` — Current namespace
+  - `ms` — Execution time in milliseconds
+  - `form` — Original form (if `eval`)
+
+On error:
+- `error` — Error object
+  - `type` — Error category
+  - `message` — Human-readable message
+- `meta` — Same as success
+
+## Human REPL Commands
+
+In human mode (`cljnim repl`):
+
+| Command | Description |
+|---|---|
+| `:quit`, `:q` | Exit REPL |
+| `:help`, `:h` | Show help |
+| `:defs` | List defined vars |
+| `:clear` | Clear definitions |
+| `:ns` | Show current namespace |
diff --git a/docs/ARCHITECTURE.bg.md b/docs/ARCHITECTURE.bg.md
new file mode 100644
index 0000000..50d0442
--- /dev/null
+++ b/docs/ARCHITECTURE.bg.md
@@ -0,0 +1,94 @@
+# Архитектура на Clojure/Nim
+
+## Общ Преглед
+
+Clojure/Nim е **компилатор**, не интерпретатор. Следва модела на ClojureScript: Clojure изходният код се чете, разширява с макроси, анализира и се генерира като Nim изходен код, който после се компилира до C и накрая до native бинарен файл.
+
+## Компилационен Пайплайн
+
+```
+┌─────────────┐
+│  .clj Файл  │
+└──────┬──────┘
+       │
+  ┌────▼────┐
+  │ Reader  │  ← EDN парсер. Произвежда Clojure структури от данни.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │ Макроси │  ← Разширение на defmacro. Работи върху Clojure данни.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │Анализатор│  ← Специални форми, locals, анализ на closures.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │ Генератор│  ← Генерира Nim AST / изходен код.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │ Nim CC  │  ← Nim → C компилация.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │   C CC  │  ← C → машинен код (GCC/Clang).
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │  Бинарен│  ← Единичен native изпълним файл.
+  └─────────┘
+```
+
+## Ключови Дизайн Решения
+
+### 1. AOT Компилатор
+Компилираме предварително (ahead-of-time), като ClojureScript. Това ни дава:
+- Бързо изпълнение (скорост на C)
+- Малък размер на бинарния файл
+- Без overhead на интерпретатор
+
+Компромисът е, че компилацията в REPL е по-бавна (всяка форма се компилира индивидуално).
+
+### 2. Clojure Макроси върху Clojure Данни
+Разширяването на макроси става **преди** да стигнем до Nim. Nim никога не вижда Clojure макроси:
+
+```clojure
+(defmacro unless [condition & body]
+  `(if (not ~condition)
+     (do ~@body)))
+```
+
+Този макро оперира върху `CljVal` обекти (Clojure списъци, символи), не върху Nim AST.
+
+### 3. Runtime в Nim
+Модулът `lib/cljnim_runtime.nim` предоставя:
+- `CljVal` — tagged union, представящ всички Clojure стойности
+- `cljAdd`, `cljMul`, и т.н. — полиморфна аритметика
+- `cljRepr` — текстово представяне
+
+### 4. Nim Interop (Бъдеще)
+Вместо Java interop, ще имаме Nim interop:
+
+```clojure
+(nim/import "strutils")
+(nim/call "strutils.join" ", " ["a" "b"])
+```
+
+## Отговорности на Модулите
+
+| Модул | Роля |
+|---|---|
+| `src/reader.nim` | Парсира `.clj` текст към `CljVal` AST |
+| `src/emitter.nim` | Трансформира `CljVal` AST в Nim изходен код |
+| `src/repl.nim` | Имплементация на human и AI REPL |
+| `src/types.nim` | Типове на AST възли (използват се от reader/emitter) |
+| `src/macros.nim` | Двигател за разширяване на макроси |
+| `src/runtime.nim` | Допълнителни runtime помощници |
+| `lib/cljnim_runtime.nim` | Основна runtime библиотека |
+
+## Модел на Паметта
+
+- Използва Nim's ORC garbage collector
+- `CljVal` е `ref object` (заделя се на heap)
+- Бъдеще: persistent структури от данни използват структурно споделяне
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..f1ffbb5
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,94 @@
+# Clojure/Nim Architecture
+
+## Overview
+
+Clojure/Nim is a **compiler**, not an interpreter. It follows the model of ClojureScript: Clojure source is read, macro-expanded, analyzed, and emitted as Nim source code, which then compiles to C and finally to a native binary.
+
+## Compilation Pipeline
+
+```
+┌─────────────┐
+│  .clj File  │
+└──────┬──────┘
+       │
+  ┌────▼────┐
+  │ Reader  │  ← EDN parser. Produces Clojure data structures.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │ Macros  │  ← defmacro expansion. Operates on Clojure data.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │ Analyzer│  ← Special forms, locals, closure analysis.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │ Emitter │  ← Generates Nim AST / source code.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │ Nim CC  │  ← Nim → C compilation.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │   C CC  │  ← C → machine code (GCC/Clang).
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │  Binary │  ← Single native executable.
+  └─────────┘
+```
+
+## Key Design Decisions
+
+### 1. AOT Compiler
+We compile ahead-of-time, like ClojureScript. This gives us:
+- Fast runtime execution (C speed)
+- Small binary size
+- No interpreter overhead
+
+The trade-off is that REPL compilation is slower (each form is compiled individually).
+
+### 2. Clojure Macros on Clojure Data
+Macro expansion happens **before** reaching Nim. Nim never sees Clojure macros:
+
+```clojure
+(defmacro unless [condition & body]
+  `(if (not ~condition)
+     (do ~@body)))
+```
+
+This macro operates on `CljVal` objects (Clojure lists, symbols), not Nim AST.
+
+### 3. Runtime in Nim
+The `lib/cljnim_runtime.nim` module provides:
+- `CljVal` — tagged union representing all Clojure values
+- `cljAdd`, `cljMul`, etc. — polymorphic arithmetic
+- `cljRepr` — string representation
+
+### 4. Nim Interop (Future)
+Instead of Java interop, we will have Nim interop:
+
+```clojure
+(nim/import "strutils")
+(nim/call "strutils.join" ", " ["a" "b"])
+```
+
+## Module Responsibilities
+
+| Module | Role |
+|---|---|
+| `src/reader.nim` | Parses `.clj` text into `CljVal` AST |
+| `src/emitter.nim` | Transforms `CljVal` AST into Nim source |
+| `src/repl.nim` | Human and AI REPL implementation |
+| `src/types.nim` | AST node types (used by reader/emitter) |
+| `src/macros.nim` | Macro expansion engine |
+| `src/runtime.nim` | Additional runtime helpers |
+| `lib/cljnim_runtime.nim` | Core runtime library |
+
+## Memory Model
+
+- Uses Nim's ORC garbage collector
+- `CljVal` is a `ref object` (heap-allocated)
+- Future: persistent data structures use structural sharing
diff --git a/docs/GUIDE.bg.md b/docs/GUIDE.bg.md
new file mode 100644
index 0000000..8887e4c
--- /dev/null
+++ b/docs/GUIDE.bg.md
@@ -0,0 +1,150 @@
+# Ръководство за Потребителя — Clojure/Nim
+
+## Инсталация
+
+### Изисквания
+- Nim >= 2.0
+- GCC или Clang
+- make
+
+### Изграждане от Източник
+```bash
+git clone https://gitlab.com/balvatar/lisp-nim.git
+cd lisp-nim
+make build
+```
+
+## CLI Команди
+
+### `compile` — Компилиране до Nim
+```bash
+./cljnim compile input.clj output.nim
+```
+Генерира `.nim` файл от Clojure изходен код.
+
+### `run` — Компилиране и Изпълнение
+```bash
+./cljnim run examples/hello.clj
+```
+Компилира до Nim, после до C, после до бинарен файл, и го изпълнява.
+
+### `read` — Парсиране и Отпечатване на AST
+```bash
+./cljnim read examples/hello.clj
+```
+Показва Clojure AST като S-изрази.
+
+### `repl` — Интерактивен REPL
+```bash
+# Човешки режим
+./cljnim repl
+
+# AI режим (структуриран JSON)
+./cljnim repl --json
+```
+
+## Писане на Clojure/Nim Програми
+
+### Базов Синтаксис
+```clojure
+; Коментарите започват с точка и запетая
+
+; Дефиниране на променлива
+(def x 42)
+
+; Дефиниране на функция
+(defn greet [name]
+  (println "Здравей, " name))
+
+; Извикване на функция
+(greet "Свят")
+
+; Аритметика
+(+ 1 2 3)      ; => 6
+(* 10 20)      ; => 200
+(/ 100 4)      ; => 25
+
+; Условни изрази
+(if (> x 0)
+  "положително"
+  "неположително")
+
+; Локални обвързвания
+(let [a 10
+      b 20]
+  (+ a b))     ; => 30
+```
+
+### Работа с Данни
+```clojure
+; Вектори (използват Nim seq вътрешно)
+(def nums [1 2 3 4 5])
+
+; Ключови думи
+(def person {:name "Алиса" :age 30})
+
+; В момента картите и множествата са ограничени.
+; Пълни persistent структури (HAMT) са в разработка.
+```
+
+### Рекурсия
+```clojure
+(defn factorial [n]
+  (if (= n 0)
+    1
+    (* n (factorial (- n 1)))))
+
+(println (factorial 5))  ; => 120
+```
+
+## Ръководство за AI REPL
+
+JSON REPL е проектиран за програмно взаимодействие.
+
+### Стартиране на AI REPL
+```bash
+./cljnim repl --json
+```
+
+### Оценка на Форма
+```json
+{"op": "eval", "form": "(+ 1 2 3)"}
+```
+Отговор:
+```json
+{
+  "status": "ok",
+  "result": {"printed": "6"},
+  "meta": {"ns": "user", "ms": 861, "form": "(+ 1 2 3)"}
+}
+```
+
+### Batch Оценка
+```json
+{"op": "eval-batch", "forms": ["(defn f [x] x)", "(f 42)"]}
+```
+
+### Листване на Дефиниции
+```json
+{"op": "get-defs"}
+```
+Отговор:
+```json
+{"status": "ok", "defs": ["f"], "ns": "user"}
+```
+
+### Изчистване на Сесия
+```json
+{"op": "clear"}
+```
+
+### Изход
+```json
+{"op": "quit"}
+```
+
+## Съвети
+
+- Използвайте `:help` в човешки REPL за налични команди.
+- Дефинициите в REPL се запазват през оценките в рамките на една сесия.
+- Флагът `--json` прави REPL изцяло машинно-четим.
diff --git a/docs/GUIDE.md b/docs/GUIDE.md
new file mode 100644
index 0000000..b83f78a
--- /dev/null
+++ b/docs/GUIDE.md
@@ -0,0 +1,150 @@
+# Clojure/Nim User Guide
+
+## Installation
+
+### Prerequisites
+- Nim >= 2.0
+- GCC or Clang
+- make
+
+### Build from Source
+```bash
+git clone https://gitlab.com/balvatar/lisp-nim.git
+cd lisp-nim
+make build
+```
+
+## CLI Commands
+
+### `compile` — Compile to Nim
+```bash
+./cljnim compile input.clj output.nim
+```
+Generates a `.nim` file from Clojure source.
+
+### `run` — Compile and Execute
+```bash
+./cljnim run examples/hello.clj
+```
+Compiles to Nim, then to C, then to a binary, and runs it.
+
+### `read` — Parse and Print AST
+```bash
+./cljnim read examples/hello.clj
+```
+Shows the Clojure AST as S-expressions.
+
+### `repl` — Interactive REPL
+```bash
+# Human-friendly mode
+./cljnim repl
+
+# AI mode (structured JSON)
+./cljnim repl --json
+```
+
+## Writing Clojure/Nim Programs
+
+### Basic Syntax
+```clojure
+; Comments start with semicolon
+
+; Define a variable
+(def x 42)
+
+; Define a function
+(defn greet [name]
+  (println "Hello, " name))
+
+; Call a function
+(greet "World")
+
+; Arithmetic
+(+ 1 2 3)      ; => 6
+(* 10 20)      ; => 200
+(/ 100 4)      ; => 25
+
+; Conditionals
+(if (> x 0)
+  "positive"
+  "non-positive")
+
+; Local bindings
+(let [a 10
+      b 20]
+  (+ a b))     ; => 30
+```
+
+### Working with Data
+```clojure
+; Vectors (use Nim seq internally)
+(def nums [1 2 3 4 5])
+
+; Keywords
+(def person {:name "Alice" :age 30})
+
+; Currently, maps and sets are limited. Full persistent
+; data structures (HAMT) are in development.
+```
+
+### Recursion
+```clojure
+(defn factorial [n]
+  (if (= n 0)
+    1
+    (* n (factorial (- n 1)))))
+
+(println (factorial 5))  ; => 120
+```
+
+## AI REPL Guide
+
+The JSON REPL is designed for programmatic interaction.
+
+### Start AI REPL
+```bash
+./cljnim repl --json
+```
+
+### Evaluate a Form
+```json
+{"op": "eval", "form": "(+ 1 2 3)"}
+```
+Response:
+```json
+{
+  "status": "ok",
+  "result": {"printed": "6"},
+  "meta": {"ns": "user", "ms": 861, "form": "(+ 1 2 3)"}
+}
+```
+
+### Batch Evaluation
+```json
+{"op": "eval-batch", "forms": ["(defn f [x] x)", "(f 42)"]}
+```
+
+### List Definitions
+```json
+{"op": "get-defs"}
+```
+Response:
+```json
+{"status": "ok", "defs": ["f"], "ns": "user"}
+```
+
+### Clear Session
+```json
+{"op": "clear"}
+```
+
+### Exit
+```json
+{"op": "quit"}
+```
+
+## Tips
+
+- Use `:help` in human REPL for available commands.
+- Definitions in REPL persist across evaluations in the same session.
+- The `--json` flag makes the REPL fully machine-readable.
diff --git a/docs/README.bg.md b/docs/README.bg.md
new file mode 100644
index 0000000..60351f6
--- /dev/null
+++ b/docs/README.bg.md
@@ -0,0 +1,106 @@
+# Clojure/Nim
+
+> Диалект на Clojure, който се компилира до Nim, после до C, и накрая до native бинарен файл.
+
+## Какво е това?
+
+Clojure/Nim е **AI-first** имплементация на езика Clojure за екосистемата на Nim. Вместо да работи върху JVM или JavaScript, компилира Clojure код директно до Nim, оттам до C, и накрая до native бинарен файл.
+
+### Защо?
+
+- **Native Performance**: Компилира се до C през Nim. Без JVM warmup, без GC паузи.
+- **Малки Бинарни Файлове**: Единични изпълними файлове, често под 1MB.
+- **Nim Ecosystem**: Директен достъп до Nim и C библиотеки през FFI.
+- **AI-Native**: Построен за AI агенти, работещи в терминал — структуриран JSON REPL, batch evaluation, git интеграция.
+
+## Бърз Старт
+
+```bash
+# Клониране
+git clone https://gitlab.com/balvatar/lisp-nim.git
+cd lisp-nim
+
+# Изграждане
+make build
+
+# Изпълнение на файл
+./cljnim run examples/hello.clj
+
+# Човешки REPL
+./cljnim repl
+
+# AI REPL (JSON режим)
+./cljnim repl --json
+```
+
+## Примери
+
+### Hello World
+```clojure
+;; examples/hello.clj
+(println "Здравей, Nim свят!")
+(println (+ 1 2 3))
+```
+
+```bash
+$ ./cljnim run examples/hello.clj
+Здравей, Nim свят!
+6
+```
+
+### Функции и Рекурсия
+```clojure
+;; examples/math.clj
+(defn square [x]
+  (* x x))
+
+(defn factorial [n]
+  (if (= n 0)
+    1
+    (* n (factorial (- n 1)))))
+
+(let [a 5]
+  (println (square a))
+  (println (factorial a)))
+```
+
+```bash
+$ ./cljnim run examples/math.clj
+25
+120
+```
+
+## AI-First REPL
+
+Clojure/Nim е построен за AI агенти. JSON REPL предоставя структуриран I/O, идеален за програмно взаимодействие.
+
+```bash
+$ ./cljnim repl --json
+{"status":"ready","ns":"user","mode":"json"}
+
+> {"op":"eval","form":"(+ 1 2 3)"}
+{"status":"ok","result":{"printed":"6"},"meta":{"ms":861}}
+
+> {"op":"eval","form":"(defn square [x] (* x x))"}
+{"status":"ok","result":{"type":"var","name":"square"}}
+
+> {"op":"eval","form":"(square 5)"}
+{"status":"ok","result":{"printed":"25"}}
+
+> {"op":"quit"}
+{"status":"ok","bye":true}
+```
+
+## Документация
+
+| Документ | Описание |
+|---|---|
+| [`GUIDE.bg.md`](GUIDE.bg.md) | Ръководство за потребителя |
+| [`ARCHITECTURE.bg.md`](ARCHITECTURE.bg.md) | Архитектура и дизайн |
+| [`AI_FIRST.bg.md`](AI_FIRST.bg.md) | AI-first философия |
+| [`API.bg.md`](API.bg.md) | REPL API референция |
+| [`ROADMAP.bg.md`](ROADMAP.bg.md) | Пътна карта за разработка |
+
+## Лиценз
+
+MIT License — вижте [LICENSE](../LICENSE).
diff --git a/docs/ROADMAP.bg.md b/docs/ROADMAP.bg.md
new file mode 100644
index 0000000..2aa48a4
--- /dev/null
+++ b/docs/ROADMAP.bg.md
@@ -0,0 +1,51 @@
+# Пътна Карта за Разработка
+
+## Фаза 0: Компилаторно Ядро ✅
+- [x] Clojure Reader (EDN парсер)
+- [x] AST → Nim Генератор
+- [x] CLI (`compile`, `run`, `read`)
+- [x] Специални форми: `def`, `defn`, `fn`, `let`, `if`, `do`, `quote`
+- [x] Аритметични оператори
+- [x] Човешки и JSON REPL
+- [x] AOT компилация до native бинарни файлове
+
+## Фаза 1: AI-Native Инструменти 🔄
+- [x] JSON REPL режим
+- [x] Batch оценка
+- [x] Структурирани грешки
+- [ ] Файлови операции (`file/read`, `file/write`)
+- [ ] Git операции (`git/commit`, `git/push`)
+- [ ] nREPL протокол съвместимост
+
+## Фаза 2: Persistent Структури от Данни
+- [ ] Persistent Vector (HAMT)
+- [ ] Persistent Map (HAMT)
+- [ ] Persistent Set
+- [ ] `conj`, `assoc`, `dissoc`, `get`, `get-in`
+- [ ] `nth`, `first`, `rest`, `last`, `count`
+
+## Фаза 3: Clojure Core Библиотека
+- [ ] Seq функции: `map`, `filter`, `reduce`, `range`
+- [ ] Низови функции: `str`, `pr-str`, `slurp`, `spit`
+- [ ] Мета: `meta`, `with-meta`, `type`
+
+## Фаза 4: Макро Система
+- [ ] `defmacro`
+- [ ] `syntax-quote`, `unquote`, `unquote-splicing`
+- [ ] `gensym`
+- [ ] Core макроси: `->`, `->>`, `and`, `or`, `when`, `cond`
+
+## Фаза 5: Nim Interop
+- [ ] `nim/import` — Импорт на Nim модули
+- [ ] `nim/call` — Извикване на Nim функции
+- [ ] C FFI декларации
+
+## Фаза 6: Оптимизация
+- [ ] AOT компилация на цели проекти
+- [ ] Кеширане на компилирани модули
+- [ ] Self-hosted REPL (компилация в паметта)
+
+## Фаза 7: Конкурентност
+- [ ] Atoms (CAS)
+- [ ] Agents
+- [ ] core.async channels (упростен вариант)
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
new file mode 100644
index 0000000..9628e9c
--- /dev/null
+++ b/docs/ROADMAP.md
@@ -0,0 +1,50 @@
+# Development Roadmap
+
+## Phase 0: Compiler Core ✅
+- [x] Clojure Reader (EDN parser)
+- [x] AST → Nim Emitter
+- [x] CLI (`compile`, `run`, `read`)
+- [x] Special forms: `def`, `defn`, `fn`, `let`, `if`, `do`, `quote`
+- [x] Arithmetic operators
+- [x] Human and JSON REPL
+
+## Phase 1: AI-Native Tooling 🔄
+- [x] JSON REPL mode
+- [x] Batch evaluation
+- [x] Structured errors
+- [ ] File operations (`file/read`, `file/write`)
+- [ ] Git operations (`git/commit`, `git/push`)
+- [ ] nREPL protocol compatibility
+
+## Phase 2: Persistent Data Structures
+- [ ] Persistent Vector (HAMT)
+- [ ] Persistent Map (HAMT)
+- [ ] Persistent Set
+- [ ] `conj`, `assoc`, `dissoc`, `get`, `get-in`
+- [ ] `nth`, `first`, `rest`, `last`, `count`
+
+## Phase 3: Clojure Core Library
+- [ ] Seq functions: `map`, `filter`, `reduce`, `range`
+- [ ] String functions: `str`, `pr-str`, `slurp`, `spit`
+- [ ] Meta: `meta`, `with-meta`, `type`
+
+## Phase 4: Macro System
+- [ ] `defmacro`
+- [ ] `syntax-quote`, `unquote`, `unquote-splicing`
+- [ ] `gensym`
+- [ ] Core macros: `->`, `->>`, `and`, `or`, `when`, `cond`
+
+## Phase 5: Nim Interop
+- [ ] `nim/import` — Import Nim modules
+- [ ] `nim/call` — Call Nim functions
+- [ ] C FFI declarations
+
+## Phase 6: Optimization
+- [ ] AOT project compilation
+- [ ] Module caching
+- [ ] Self-hosted REPL (compile in memory)
+
+## Phase 7: Concurrency
+- [ ] Atoms (CAS)
+- [ ] Agents
+- [ ] core.async channels (simplified)