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/03-ai-integration.md

@@ -0,0 +1,112 @@
+
+[← Back to Index](index.md)
+
+---
+
+# AI-First Design Philosophy
+
+## Why AI-First?
+
+Modern software development is increasingly done by **AI agents** operating in terminal environments. These agents do not use GUIs, IDEs, or syntax highlighting. They need:
+
+1. **Structured I/O** — JSON/EDN, not plain text
+2. **Programmatic Control** — Every operation must be scriptable
+3. **Self-Describing Systems** — AI can discover capabilities at runtime
+4. **Git Integration** — Version control as part of the workflow
+
+## Principles
+
+### 1. Structured I/O
+
+All REPL communication uses JSON:
+
+```json
+// Input
+{"op": "eval", "form": "(+ 1 2)", "request-id": "uuid"}
+
+// Output
+{
+  "status": "ok",
+  "request-id": "uuid",
+  "result": {"type": "int", "value": 3, "printed": "3"},
+  "meta": {"ms": 0.5, "ns": "user"}
+}
+```
+
+### 2. Batch Operations
+
+AI agents evaluate multiple forms at once:
+
+```json
+{"op": "eval-batch",
+ "forms": [
+   "(defn add [a b] (+ a b))",
+   "(add 10 20)"
+ ]}
+```
+
+### 3. Session Persistence
+
+Definitions persist within a REPL session, allowing incremental development:
+
+```json
+{"op": "eval", "form": "(defn square [x] (* x x))"}
+{"op": "eval", "form": "(square 5)"}
+{"op": "get-defs"}
+```
+
+### 4. Error Recovery
+
+All errors are structured with type, message, and context:
+
+```json
+{
+  "status": "error",
+  "error": {
+    "type": "compiler/unknown-symbol",
+    "symbol": "unknwon-fn",
+    "message": "Unknown symbol: unknwon-fn",
+    "form": "(unknwon-fn 1 2)"
+  }
+}
+```
+
+## AI Workflow
+
+```bash
+# 1. Clone repo
+git clone git@gitlab.com:balvatar/lisp-nim.git
+cd lisp-nim
+
+# 2. Start AI REPL
+cljnim repl --json
+
+# 3. AI evaluates forms, gets structured responses
+# 4. AI writes files via (file/write ...) [future]
+# 5. AI commits via (git/commit ...) [future]
+# 6. AI pushes via (git/push) [future]
+```
+
+## Comparison
+
+| Aspect | Human IDE | AI Terminal |
+|---|---|---|
+| Interface | GUI + mouse | Text + commands |
+| Navigation | Clicking | `(apropos ...)`, `(doc ...)` |
+| Refactoring | Manual | Batch eval + git diff |
+| Testing | Run button | `(run-tests)` structured response |
+| Commit | GUI dialog | `(git/commit "msg")` |
+
+## Future: Tool-Call Format
+
+Direct integration with AI frameworks:
+
+```json
+{
+  "tool": "cljnim/eval",
+  "arguments": {
+    "code": "(defn fib [n] ...)",
+    "mode": "compile"
+  }
+}
+```