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
2026-05-08 23:24:47 +03:00
parent 2b32640eeb
commit 10e4ec07d6
18 changed files with 490 additions and 443 deletions
@@ -0,0 +1,127 @@
+
+[← Към индекса](index.md)
+
+---
+
+# Първи стъпки
+
+> Диалект на Clojure, който се компилира до Nim → C → нативен бинарен файл.
+
+## Изисквания
+
+- **Nim** >= 2.0.0
+- **GCC** или **Clang**
+- **make**
+- **curl** (за AI функциите, незадължително)
+
+## Инсталация
+
+```bash
+git clone https://gitlab.com/balvatar/lisp-nim.git
+cd lisp-nim
+make build
+```
+
+## Проверка
+
+```bash
+make check    # компилация + 276+ теста + всички примери
+```
+
+## CLI Команди
+
+| Команда | Описание |
+|---------|----------|
+| `./cljnim compile <file.clj>` | Компилиране до Nim изходен код |
+| `./cljnim compile-lib <file.clj>` | Компилиране с експортирани функции (`*`) |
+| `./cljnim run <file.clj>` | Компилиране и изпълнение |
+| `./cljnim read <file.clj>` | Парсиране и печат на AST |
+| `./cljnim repl` | Стартиране на човешки REPL |
+| `./cljnim repl --json` | JSON REPL (за AI агенти) |
+| `./cljnim deps` | Разрешаване на зависимости от `deps.edn` |
+| `./cljnim -e '<код>'` | Оценка на израз |
+| `./cljnim ai '<описание>'` | Генериране на Clojure код с AI |
+
+## Бързи примери
+
+### Hello World
+```clojure
+;; examples/hello.clj
+(println "Hello, Nim world!")
+(println (+ 1 2 3))
+```
+
+```bash
+$ ./cljnim run examples/hello.clj
+Hello, Nim world!
+6
+```
+
+### Функции и рекурсия
+```clojure
+(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)))
+```
+
+### loop/recur
+```clojure
+(defn sum [n]
+  (loop [acc 0 i 1]
+    (if (> i n)
+      acc
+      (recur (+ acc i) (inc i)))))
+(println (sum 10))  ;; => 55
+```
+
+### Atoms (REPL)
+```clojure
+user> (def a (atom 0))
+user> (swap! a inc)
+1
+user> (reset! a 42)
+42
+user> (deref a)
+42
+```
+
+## AI Настройка (незадължително)
+
+```bash
+export DEEPSEEK_API_KEY="sk-..."
+# или OPENAI_API_KEY, или MIMO_API_KEY
+```
+
+Виж [03-ai-integration.md](03-ai-integration.md) за пълна AI документация.
+
+## Структура на проекта
+
+```
+├── src/              # Изходен код на компилатора
+│   ├── cljnim.nim    # CLI входна точка
+│   ├── reader.nim    # EDN парсер
+│   ├── emitter.nim   # Clojure AST → Nim
+│   ├── eval.nim      # Интерпретатор (REPL бърз път)
+│   └── ai_assist.nim # AI API интеграция
+├── lib/              # Runtime библиотеки
+│   ├── cljnim_runtime.nim      # Нативен runtime
+│   └── cljnim_runtime_js.nim   # JS runtime
+├── tests/            # Тестове (8 файла, 276+ теста)
+├── examples/         # Примери .clj
+├── benchmarks/       # Бенчмаркове
+├── docs/             # Документация
+└── experiments/      # Web, WASM, native-lib target-и
+```
+
+## Следващи стъпки
+
+- [02-architecture.md](02-architecture.md) — Как работи компилаторът
+- [03-ai-integration.md](03-ai-integration.md) — AI-асистирана разработка
+- [04-api-reference.md](04-api-reference.md) — JSON REPL протокол
+- [05-user-guide.md](05-user-guide.md) — Макроси, interop, напреднали шаблони