Add bilingual documentation (EN + BG) in docs/

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 изцяло машинно-четим.