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/en/05-user-guide.md

@@ -0,0 +1,155 @@
+
+[← Back to Index](index.md)
+
+---
+
+# Clojure/Nim User Guide
+
+## Installation
+
+### Prerequisites
+- Nim >= 2.0
+- GCC or Clang
+- make
+
+### Build from Source
+```bash
+git clone https://gitlab.com/balvatar/lisp-nim.git
+cd lisp-nim
+make build
+```
+
+## CLI Commands
+
+### `compile` — Compile to Nim
+```bash
+./cljnim compile input.clj output.nim
+```
+Generates a `.nim` file from Clojure source.
+
+### `run` — Compile and Execute
+```bash
+./cljnim run examples/hello.clj
+```
+Compiles to Nim, then to C, then to a binary, and runs it.
+
+### `read` — Parse and Print AST
+```bash
+./cljnim read examples/hello.clj
+```
+Shows the Clojure AST as S-expressions.
+
+### `repl` — Interactive REPL
+```bash
+# Human-friendly mode
+./cljnim repl
+
+# AI mode (structured JSON)
+./cljnim repl --json
+```
+
+## Writing Clojure/Nim Programs
+
+### Basic Syntax
+```clojure
+; Comments start with semicolon
+
+; Define a variable
+(def x 42)
+
+; Define a function
+(defn greet [name]
+  (println "Hello, " name))
+
+; Call a function
+(greet "World")
+
+; Arithmetic
+(+ 1 2 3)      ; => 6
+(* 10 20)      ; => 200
+(/ 100 4)      ; => 25
+
+; Conditionals
+(if (> x 0)
+  "positive"
+  "non-positive")
+
+; Local bindings
+(let [a 10
+      b 20]
+  (+ a b))     ; => 30
+```
+
+### Working with Data
+```clojure
+; Vectors (use Nim seq internally)
+(def nums [1 2 3 4 5])
+
+; Keywords
+(def person {:name "Alice" :age 30})
+
+; Maps and sets use persistent HAMT data structures
+; with structural sharing and O(log₃₂ n) operations.
+```
+
+### Recursion
+```clojure
+(defn factorial [n]
+  (if (= n 0)
+    1
+    (* n (factorial (- n 1)))))
+
+(println (factorial 5))  ; => 120
+```
+
+## AI REPL Guide
+
+The JSON REPL is designed for programmatic interaction.
+
+### Start AI REPL
+```bash
+./cljnim repl --json
+```
+
+### Evaluate a Form
+```json
+{"op": "eval", "form": "(+ 1 2 3)"}
+```
+Response:
+```json
+{
+  "status": "ok",
+  "result": {"printed": "6"},
+  "meta": {"ns": "user", "ms": 861, "form": "(+ 1 2 3)"}
+}
+```
+
+### Batch Evaluation
+```json
+{"op": "eval-batch", "forms": ["(defn f [x] x)", "(f 42)"]}
+```
+
+### List Definitions
+```json
+{"op": "get-defs"}
+```
+Response:
+```json
+{"status": "ok", "defs": ["f"], "ns": "user"}
+```
+
+### Clear Session
+```json
+{"op": "clear"}
+```
+
+### Exit
+```json
+{"op": "quit"}
+```
+
+## Tips
+
+- Use `:help` in human REPL for available commands.
+- Definitions in REPL persist across evaluations in the same session.
+- The `--json` flag makes the REPL fully machine-readable.