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,112 @@
+
+[← Към индекса](index.md)
+
+---
+
+# 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"
+  }
+}
+```