Add bilingual documentation (EN + BG) in docs/

docs/GUIDE.md

@@ -0,0 +1,150 @@
+# 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})
+
+; Currently, maps and sets are limited. Full persistent
+; data structures (HAMT) are in development.
+```
+
+### 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.