docs: highlight unique advantages — standalone, HAMT, multi-target

Update README and architecture docs to emphasize: - Complete independence from Java ecosystem (JVM, GraalVM, Closure) - Native HAMT persistent data structures built from scratch in Nim - Multi-target compilation (native, shared lib, WASM, JS) - AI-native tooling and concurrency without JVM threads Updates both English and Bulgarian documentation.
2026-05-08 23:59:24 +03:00
parent 23252826a0
commit 4739e2c151
5 changed files with 194 additions and 56 deletions
@@ -45,6 +45,40 @@ Clojure/Nim is a **compiler**, not an interpreter. It follows the model of Cloju
  └─────────┘
 ```

+## Unique Advantages
+
+### Independence from the Java Ecosystem
+Clojure/Nim is the **only** Clojure dialect with absolutely no dependency on the Java ecosystem:
+
+| Dialect | JVM Required | GraalVM | Google Closure | Java stdlib |
+|---------|-------------|---------|----------------|-------------|
+| Clojure (JVM) | ✅ | ❌ | ❌ | ✅ |
+| ClojureScript | ❌ | ❌ | ✅ | ❌ |
+| Babashka | ❌ | ✅ | ❌ | Partial |
+| **Clojure/Nim** | ❌ | ❌ | ❌ | ❌ |
+
+This means:
+- **No JVM warmup** — binaries start instantly
+- **No GraalVM complexity** — no native-image configuration
+- **No Java installation required** — the compiler itself is a single binary
+- **True standalone deployment** — one file, zero runtime dependencies
+
+### Native HAMT Implementation
+Our persistent data structures are built from scratch in Nim, optimized for Nim's ORC garbage collector:
+- **32-way branching** like Clojure's `PersistentVector`, but without Java object overhead
+- **Structural sharing** via copy-on-write HAMT nodes
+- **O(log₃₂ n)** for `assoc`/`dissoc`/`nth` — same asymptotic complexity as JVM Clojure
+- **Nim ref objects** instead of Java interfaces — simpler memory layout, better cache locality
+
+### Multi-Target Compilation
+The same Clojure source compiles to four different targets from one codebase:
+1. **Native binary** — `nim c` → C → machine code
+2. **Shared library** — `nim c --app:lib` → `.so` / `.dll` / `.dylib`
+3. **WASM** — `nim c -d:emscripten` → browser-native WebAssembly
+4. **JavaScript** — `nim js` → browser/Node.js
+
+No other Clojure implementation offers this breadth of targets without external tools.
+
 ## Key Design Decisions

 ### 1. AOT Compiler
@@ -1,36 +1,38 @@
-
-[← Back to Index](index.md)
-
---
-
-# Clojure/Nim Documentation (English)
+# Clojure/Nim Documentation

 > A Clojure dialect that compiles to Nim → C → native binaries.
+> **The only standalone Clojure implementation completely free from the Java ecosystem.**

-## Table of Contents
+## Choose Language / Избор на език

-| # | 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 |
+| 🇬🇧 English | 🇧🇬 Български |
+|------------|-------------|
+| [English Documentation](en/index.md) | [Българска Документация](bg/index.md) |

-## Quick Start
+## Quick Links

-```bash
-git clone https://gitlab.com/balvatar/lisp-nim.git
-cd lisp-nim
-make build
-make check        # build + tests + examples
-./cljnim repl     # human REPL
-```
+- **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

-## Stats
+## Why Clojure/Nim?

- **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
+Unlike every other Clojure dialect, Clojure/Nim has **zero dependency on the Java ecosystem** — no JVM, no GraalVM, no Google Closure Compiler, no Java standard library.
+
+| Dialect | Java Ecosystem Dependency |
+|---------|---------------------------|
+| Clojure (JVM) | Full — runs on JVM |
+| ClojureScript | Heavy — Google Closure Compiler |
+| Babashka | Medium — GraalVM native-image |
+| **Clojure/Nim** | **None — completely standalone** |
+
+### Unique Advantages
+
+1. **Native HAMT Persistent Data Structures** — Built from scratch in Nim (Persistent Vector, Map, Set with structural sharing)
+2. **Multiple Targets** — Native binary, shared library (.so/.dll), WASM, and JavaScript from one codebase
+3. **AOT Compiler** — Clojure → Nim → C → native, running at C speed
+4. **Nim/C Interop** — Direct FFI without JVM bridging overhead
+5. **AI-Native Tooling** — Built-in AI integration for code generation, optimization, and debugging
+6. **Concurrency Without JVM** — Atoms, Agents, and core.async channels without Java threads
+7. **Tiny Binaries** — Single executables under 1MB with no runtime dependencies