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
@@ -1,71 +0,0 @@
-# Phase 5: HAMT Persistent Vector
-
-## Status: COMPLETE
-
-### What was implemented
-
-**Hash Array Mapped Trie (HAMT) Persistent Vector** — 32-way branching trie with path-copying structural sharing, matching Clojure's `PersistentVector` semantics.
-
- `lib/cljnim_pvec.nim` — Core implementation
-  - `PersistentVector[T]` — root pointer + count + shift + tail
-  - `pvecConj` — O(log₃₂ N) append with structural sharing
-  - `pvecNth` — O(log₃₂ N) random access
-  - `pvecAssoc` — O(log₃₂ N) update with path copying
-  - `pvecPop` — O(log₃₂ N) remove last
-  - `newPersistentVector` — builder from `seq[T]`
-  - `toSeq` — convert back to `seq[T]`
-  - `len`, `[]` overloads for seq-like interface
-
-**Integration into Runtime**
- `lib/cljnim_runtime.nim`: `ckVector` now stores `PersistentVector[CljVal]`
- All 51 `vecData` references migrated to use `pvecNth`/`toSeq`/`count`
- `cljVector` constructor builds from `seq[CljVal]` via `newPersistentVector`
-
-### Architecture Decisions
-
-1. **Tail optimization**: Like Clojure, maintains a 32-element tail buffer for fast append of recent items
-2. **Lazy tree growth**: Root promotion only happens when tree is full (`needsNewRoot` check)
-3. **Path copying**: Every `conj`/`assoc` copies only the nodes along the path to the changed leaf
-4. **Seq compatibility**: Added `len` and `[]` overloads so `mapIt`, `join`, `items` iterator work transparently
-
-### Bug fixes during implementation
-
- **Recursive `pushLeaf` bug**: When `child.isNil` and `shift != BRANCHING_BITS`, was creating empty internal nodes without recursing to place the leaf. Fixed by calling `pushLeaf(newInternalNode(), index, shift-5, val)` instead of just `newInternalNode()`.
-
-### Tests
-
- `tests/test_pvec.nim` — 14 tests covering:
-  - Empty vector, single element, few elements
-  - `conj` one-by-one (100 elements)
-  - `conj` across tail boundary (32)
-  - `conj` across second level (1024)
-  - `conj` large (10000)
-  - `assoc` in tail and tree
-  - `assoc` preserves old vector (structural sharing)
-  - `pop` from tail, across boundary, to empty
-
-### Performance Characteristics
-
-| Operation | Complexity | Notes |
-|-----------|-----------|-------|
-| `conj` | O(log₃₂ N) | ~1-3 node copies |
-| `nth` | O(log₃₂ N) | ~3-5 pointer hops |
-| `assoc` | O(log₃₂ N) | ~1-3 node copies |
-| `pop` | O(log₃₂ N) | May pull leaf into tail |
-| `toSeq` | O(N) | Full traversal |
-
-For N ≤ 1M, depth ≤ 3 (shift ≤ 15), making operations effectively constant-time.
-
-### Migration Guide for Other AIs
-
-If you need to work with vectors in `cljnim_runtime.nim`:
-
-```nim
-# Instead of:
-v.vecData.len        # Use: v.vecData.count
-v.vecData[0]         # Use: pvecNth(v.vecData, 0)
-v.vecData[1..^1]     # Use: toSeq(v.vecData)[1..^1]
-for item in v.vecData:  # Use: for item in v.vecData.items:
-```
-
-`mapIt` from `sequtils` works transparently thanks to `len` + `items` iterator overloads.
@@ -1,106 +0,0 @@
-# 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).
@@ -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, напреднали шаблони
@@ -1,3 +1,8 @@
+
+[← Към индекса](index.md)
+
+---
+
 # Архитектура на Clojure/Nim

 ## Общ Преглед
@@ -67,14 +72,16 @@ Clojure/Nim е **компилатор**, не интерпретатор. Сле
 - `cljAdd`, `cljMul`, и т.н. — полиморфна аритметика
 - `cljRepr` — текстово представяне

-### 4. Nim Interop (Бъдеще)
-Вместо Java interop, ще имаме Nim interop:
+### 4. Nim Interop
+Вместо Java interop, имаме директен Nim interop:

 ```clojure
-(nim/import "strutils")
-(nim/call "strutils.join" ", " ["a" "b"])
+(nim/math/sin x)
+(nim/strutils/toUpper s)
 ```

+Nim модулите се импортират автоматично при извикване през `nim/module/fn` шаблона.
+
 ## Отговорности на Модулите

 | Модул | Роля |
@@ -82,13 +89,19 @@ Clojure/Nim е **компилатор**, не интерпретатор. Сле
 | `src/reader.nim` | Парсира `.clj` текст към `CljVal` AST |
 | `src/emitter.nim` | Трансформира `CljVal` AST в Nim изходен код |
 | `src/repl.nim` | Имплементация на human и AI REPL |
+| `src/eval.nim` | Tree-walking interpreter за бързо in-memory eval |
+| `src/deps.nim` | Резолюция на зависимости (deps.edn формат) |
+| `src/core.nim` | Core runtime функции (AOT компилирани) |
 | `src/types.nim` | Типове на AST възли (използват се от reader/emitter) |
 | `src/macros.nim` | Двигател за разширяване на макроси |
 | `src/runtime.nim` | Допълнителни runtime помощници |
 | `lib/cljnim_runtime.nim` | Основна runtime библиотека |
+| `lib/cljnim_pvec.nim` | Persistent Vector (HAMT имплементация) |
+| `lib/cljnim_pmap.nim` | Persistent Hash Map (HAMT имплементация) |
+| `lib/cljnim_async.nim` | core.async channels runtime |

 ## Модел на Паметта

 - Използва Nim's ORC garbage collector
 - `CljVal` е `ref object` (заделя се на heap)
- Бъдеще: persistent структури от данни използват структурно споделяне
+- Persistent структури от данни (Vector, Map, Set) използват структурно споделяне през HAMT
@@ -1,3 +1,8 @@
+
+[← Към индекса](index.md)
+
+---
+
 # AI-First Философия на Дизайна

 ## Защо AI-First?
@@ -1,3 +1,8 @@
+
+[← Към индекса](index.md)
+
+---
+
 # REPL API Референция

 ## JSON REPL Протокол
@@ -1,3 +1,8 @@
+
+[← Към индекса](index.md)
+
+---
+
 # Ръководство за Потребителя — Clojure/Nim

 ## Инсталация
@@ -83,8 +88,8 @@ make build
 ; Ключови думи
 (def person {:name "Алиса" :age 30})

-; В момента картите и множествата са ограничени.
-; Пълни persistent структури (HAMT) са в разработка.
+; Картите и множествата използват persistent HAMT структури
+; със structural sharing и O(log₃₂ n) операции.
 ```

 ### Рекурсия
@@ -1,3 +1,8 @@
+
+[← Към индекса](index.md)
+
+---
+
 # Пътна Карта за Разработка

 ## Фаза 0: Компилаторно Ядро ✅
@@ -41,42 +46,41 @@
 - [x] Файлови операции: `(file/ls "dir")`, `(file/exists? "path")`
 - [x] Git операции: `(git/status)`, `(git/commit "msg")`, `(git/push)`
 - [x] Git операции: `(git/diff)`, `(git/log)`
- [ ] nREPL протокол съвместимост
- [ ] Tool-call формат за интеграция с AI frameworks
+- [x] nREPL протокол съвместимост (JSON over TCP, `--tcp PORT`)
+- [x] Tool-call формат за интеграция с AI frameworks

-## Фаза 5: Persistent Структури от Данни
- [ ] Persistent Vector (Hash Array Mapped Trie)
- [ ] Persistent Map (HAMT)
- [ ] Persistent Set
- [ ] `conj`, `assoc`, `dissoc`, `get`, `get-in`
- [ ] `nth`, `first`, `rest`, `last`, `count` върху persistent колекции
- [ ] Transients за batch мутации
+## Фаза 5: Persistent Структури от Данни ✅ (Завършена)
+- [x] Persistent Vector (Hash Array Mapped Trie, 32-way branching)
+- [x] Persistent Map (HAMT) — `pmapAssoc`, `pmapDissoc`, `pmapGet` в O(log₃₂ n)
+- [x] Persistent Set
+- [x] `conj`, `assoc`, `dissoc`, `get`, `get-in`
+- [x] `nth`, `first`, `rest`, `last`, `count` върху persistent колекции
+- [x] Transients за batch мутации
+- [x] `conj!`, `assoc!`, `persistent!`

-## Фаза 6: Clojure Core Библиотека
- [ ] `range`, `repeat`, `cycle`, `iterate`
- [ ] `take`, `drop`, `partition`, `interleave`, `concat`
- [ ] `str`, `pr-str`, `println`, `prn`
- [ ] `slurp`, `spit`, `read-line`
- [ ] `meta`, `with-meta`, `vary-meta`
- [ ] `type`, `instance?`, `satisfies?`
+## Фаза 6: Clojure Core Библиотека ✅ (Завършена)
+- [x] `range`, `repeat`, `cycle`, `iterate`
+- [x] `take`, `drop`, `partition`, `interleave`, `concat`
+- [x] `str`, `pr-str`, `println`, `prn`
+- [x] `slurp`, `spit`, `read-line`
+- [x] `meta`, `with-meta`, `vary-meta`
+- [x] `type`, `instance?`, `satisfies?`

-## Фаза 7: Компилация на Проекти
- [ ] Компилиране на цели проекти (не само отделни файлове)
- [ ] Система за namespaces (`ns`, `require`, `use`)
- [ ] Кеширане на модули за по-бърз REPL старт
- [ ] Резолюция на зависимости
+## Фаза 7: Компилация на Проекти ✅
+- [x] Компилиране на цели проекти (не само отделни файлове)
+- [x] Система за namespaces (`ns`, `(:require [lib :as alias])`)
+- [x] Кеширане на модули за по-бърз REPL старт
+- [x] Резолюция на зависимости (deps.edn, Git deps към .deps/)

-## Фаза 8: Self-Hosted REPL
- [ ] Компилиране на форми в паметта (без temp файлове)
- [ ] Бърз REPL старт (< 100ms)
- [ ] Hot code reloading
+## Фаза 8: Self-Hosted REPL ✅
+- [x] Компилиране на форми в паметта (tree-walking interpreter, <1ms eval)
+- [x] Бърз REPL старт (~0.02ms на eval спрямо 1133ms компилиран)
+- [x] Hot code reloading (def/defn обновяват средата незабавно)

-## Фаза 9: Конкурентност
- [ ] Atoms (compare-and-swap)
- [ ] Agents
- [ ] core.async channels (упростен вариант)
+## Фаза 9: Конкурентност ✅
+- [x] Atoms (compare-and-swap)
+- [x] Agents (send, await, deref — sync dispatch в interpreter)
+- [x] core.async channels (chan, >!, <!, close!, go — interpreter-first)

 ## Известни Проблеми
 - `->>` threading macro с вложени `map`/`reduce` изисква правилен macro expansion контекст
- REPL дефинициите се прекомпилират от нулата при всяка оценка (бавно, но коректно)
- Няма истински persistent структури от данни (runtime използва Nim seq/tables)
@@ -0,0 +1,36 @@
+
+[← Към индекса](index.md)
+
+---
+
+# Clojure/Nim Документация (Български)
+
+> Диалект на Clojure, който се компилира до Nim → C → нативен бинарен файл.
+
+## Съдържание
+
+| # | Документ | Описание |
+|---|----------|----------|
+| 01 | [Първи стъпки](01-getting-started.md) | Инсталация, компилация, CLI команди, бързи примери |
+| 02 | [Архитектура](02-architecture.md) | Компилационен pipeline, дизайн решения, вътрешна структура |
+| 03 | [AI Интеграция](03-ai-integration.md) | DeepSeek, OpenAI, MiMo — помощ при грешки, генериране на код, оптимизация, дебъг |
+| 04 | [API Справочник](04-api-reference.md) | JSON REPL протокол, операции, tool-call формат |
+| 05 | [Ръководство](05-user-guide.md) | Макроси, threading, interop, напреднали шаблони |
+| 06 | [Пътна карта](06-roadmap.md) | Завършени фази, бъдещи планове, цели за перформанс |
+
+## Бърз старт
+
+```bash
+git clone https://gitlab.com/balvatar/lisp-nim.git
+cd lisp-nim
+make build
+make check        # компилация + тестове + примери
+./cljnim repl     # човешки REPL
+```
+
+## Статистика
+
+- **Тестове:** 276+ в 8 suite-а
+- **Компилатор:** Nim → C → нативен код
+- **Target-и:** Linux, macOS, Windows, JS, WASM, C shared libraries
+- **AI Поддръжка:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo
@@ -0,0 +1,127 @@
+
+[← Back to Index](index.md)
+
+---
+
+# Getting Started
+
+> A Clojure dialect that compiles to Nim → C → native binaries.
+
+## Prerequisites
+
+- **Nim** >= 2.0.0
+- **GCC** or **Clang**
+- **make**
+- **curl** (for AI features, optional)
+
+## Installation
+
+```bash
+git clone https://gitlab.com/balvatar/lisp-nim.git
+cd lisp-nim
+make build
+```
+
+## Verify Installation
+
+```bash
+make check    # build + 276+ tests + all examples
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `./cljnim compile <file.clj>` | Compile to Nim source |
+| `./cljnim compile-lib <file.clj>` | Compile to Nim with exported functions (`*`) |
+| `./cljnim run <file.clj>` | Compile and run binary |
+| `./cljnim read <file.clj>` | Parse and print AST |
+| `./cljnim repl` | Start human REPL |
+| `./cljnim repl --json` | Start JSON REPL (for AI agents) |
+| `./cljnim deps` | Resolve dependencies from `deps.edn` |
+| `./cljnim -e '<code>'` | Evaluate expression |
+| `./cljnim ai '<description>'` | Generate Clojure code with AI |
+
+## Quick Examples
+
+### Hello World
+```clojure
+;; examples/hello.clj
+(println "Hello, Nim world!")
+(println (+ 1 2 3))
+```
+
+```bash
+$ ./cljnim run examples/hello.clj
+Hello, Nim world!
+6
+```
+
+### Functions & Recursion
+```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 Setup (Optional)
+
+```bash
+export DEEPSEEK_API_KEY="sk-..."
+# or OPENAI_API_KEY, or MIMO_API_KEY
+```
+
+See [03-ai-integration.md](03-ai-integration.md) for full AI documentation.
+
+## Project Structure
+
+```
+├── src/              # Compiler source
+│   ├── cljnim.nim    # CLI entry point
+│   ├── reader.nim    # EDN parser
+│   ├── emitter.nim   # Clojure AST → Nim
+│   ├── eval.nim      # Tree-walking interpreter (REPL fast path)
+│   └── ai_assist.nim # AI API integration
+├── lib/              # Runtime libraries
+│   ├── cljnim_runtime.nim      # Native runtime
+│   └── cljnim_runtime_js.nim   # JS runtime
+├── tests/            # Test suites (8 files, 276+ tests)
+├── examples/         # Example .clj files
+├── benchmarks/       # Performance benchmarks
+├── docs/             # Documentation
+└── experiments/      # Web, WASM, native-lib targets
+```
+
+## Next Steps
+
+- [02-architecture.md](02-architecture.md) — How the compiler works
+- [03-ai-integration.md](03-ai-integration.md) — AI-powered development
+- [04-api-reference.md](04-api-reference.md) — JSON REPL protocol
+- [05-user-guide.md](05-user-guide.md) — Macros, interop, advanced patterns
@@ -1,3 +1,8 @@
+
+[← Back to Index](index.md)
+
+---
+
 # Clojure/Nim Architecture

 ## Overview
@@ -67,14 +72,16 @@ The `lib/cljnim_runtime.nim` module provides:
 - `cljAdd`, `cljMul`, etc. — polymorphic arithmetic
 - `cljRepr` — string representation

-### 4. Nim Interop (Future)
-Instead of Java interop, we will have Nim interop:
+### 4. Nim Interop
+Instead of Java interop, we have direct Nim interop:

 ```clojure
-(nim/import "strutils")
-(nim/call "strutils.join" ", " ["a" "b"])
+(nim/math/sin x)
+(nim/strutils/toUpper s)
 ```

+Nim modules are auto-imported when called via the `nim/module/fn` pattern.
+
 ## Module Responsibilities

 | Module | Role |
@@ -82,13 +89,19 @@ Instead of Java interop, we will have Nim interop:
 | `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/eval.nim` | Tree-walking interpreter for fast in-memory eval |
+| `src/deps.nim` | Dependency resolution (deps.edn format) |
+| `src/core.nim` | Core runtime functions (AOT compiled) |
 | `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 |
+| `lib/cljnim_pvec.nim` | Persistent Vector (HAMT implementation) |
+| `lib/cljnim_pmap.nim` | Persistent Hash Map (HAMT implementation) |
+| `lib/cljnim_async.nim` | core.async channels runtime |

 ## Memory Model

 - Uses Nim's ORC garbage collector
 - `CljVal` is a `ref object` (heap-allocated)
- Future: persistent data structures use structural sharing
+- Persistent data structures (Vector, Map, Set) use structural sharing via HAMT
@@ -1,3 +1,8 @@
+
+[← Back to Index](index.md)
+
+---
+
 # AI-First Design Philosophy

 ## Why AI-First?
@@ -1,3 +1,8 @@
+
+[← Back to Index](index.md)
+
+---
+
 # REPL API Reference

 ## JSON REPL Protocol
@@ -1,3 +1,8 @@
+
+[← Back to Index](index.md)
+
+---
+
 # Clojure/Nim User Guide

 ## Installation
@@ -83,8 +88,8 @@ Shows the Clojure AST as S-expressions.
 ; Keywords
 (def person {:name "Alice" :age 30})

-; Currently, maps and sets are limited. Full persistent
-; data structures (HAMT) are in development.
+; Maps and sets use persistent HAMT data structures
+; with structural sharing and O(log₃₂ n) operations.
 ```

 ### Recursion
@@ -1,3 +1,8 @@
+
+[← Back to Index](index.md)
+
+---
+
 # Development Roadmap

 ## Phase 0: Compiler Core ✅
@@ -0,0 +1,36 @@
+
+[← Back to Index](index.md)
+
+---
+
+# Clojure/Nim Documentation (English)
+
+> A Clojure dialect that compiles to Nim → C → native binaries.
+
+## Table of Contents
+
+| # | Document | Description |
+|---|----------|-------------|
+| 01 | [Getting Started](01-getting-started.md) | Installation, build, CLI commands, quick examples |
+| 02 | [Architecture](02-architecture.md) | Compiler pipeline, design decisions, internal structure |
+| 03 | [AI Integration](03-ai-integration.md) | DeepSeek, OpenAI, MiMo — error assistance, code generation, optimization, debugging |
+| 04 | [API Reference](04-api-reference.md) | JSON REPL protocol, operations, tool-call format |
+| 05 | [User Guide](05-user-guide.md) | Macros, threading, interop, advanced patterns |
+| 06 | [Roadmap](06-roadmap.md) | Completed phases, future plans, performance targets |
+
+## Quick Start
+
+```bash
+git clone https://gitlab.com/balvatar/lisp-nim.git
+cd lisp-nim
+make build
+make check        # build + tests + examples
+./cljnim repl     # human REPL
+```
+
+## Stats
+
+- **Tests:** 276+ across 8 suites
+- **Compiler:** Nim → C → native
+- **Targets:** Linux, macOS, Windows, JS, WASM, C shared libraries
+- **AI Support:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo
@@ -0,0 +1,16 @@
+# Clojure/Nim Documentation
+
+> A Clojure dialect that compiles to Nim → C → native binaries.
+
+## Choose Language / Избор на език
+
+| 🇬🇧 English | 🇧🇬 Български |
+|------------|-------------|
+| [English Documentation](en/index.md) | [Българска Документация](bg/index.md) |
+
+## Quick Links
+
+- **GitHub/GitLab:** [lisp-nim](https://gitlab.com/balvatar/lisp-nim)
+- **Build:** `make build && make check`
+- **Tests:** 276+ tests across 8 test suites
+- **AI Integration:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo