docs: reorganize into en/ and bg/ subfolders with numbered indices

- New docs/index.md with language selector
- docs/en/ — 01-getting-started, 02-architecture, 03-ai-integration,
  04-api-reference, 05-user-guide, 06-roadmap
- docs/bg/ — same structure in Bulgarian
- Root README.md trimmed to quick-start + links to docs/
- Removed old flat docs/ files (ARCHITECTURE.md, AI_FIRST.md, etc.)
- Added swap!/reset! examples to getting-started guides

docs/bg/05-user-guide.md

@@ -0,0 +1,155 @@
+
+[← Към индекса](index.md)
+
+---
+
+# Ръководство за Потребителя — 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 структури
+; със structural sharing и O(log₃₂ n) операции.
+```
+
+### Рекурсия
+```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 изцяло машинно-четим.