From d3feeba1952eb8d4d5037157817998cf9356401f Mon Sep 17 00:00:00 2001
From: DualFroz <me@dualfroz.com>
Date: Fri, 28 Aug 2026 22:40:00 +0200
Subject: [PATCH] docs: add project readme

---
 README.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f5f2bb7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,92 @@
+# Lumen
+
+Lumen is a small dynamically-typed scripting language implemented in Kotlin. Source
+is scanned into tokens, parsed into an abstract syntax tree, compiled to a compact
+bytecode representation, and executed on a stack-based virtual machine.
+
+## Features
+
+- First-class functions and closures that capture mutable state
+- `let` / `var` bindings with lexical scoping
+- Control flow: `if` / `else`, `while`, and `for ... in` loops
+- Lists and maps with literal syntax and built-in methods
+- String, list, and map methods plus a small numeric standard library
+- A module system driven by `import` for splitting programs across files
+- Built-ins such as `print`, `println`, `len`, `type`, `str`, `int`, `assert`,
+  `map`, `filter`, and `reduce`
+- An interactive REPL and a file runner
+
+## Building
+
+The project uses the Gradle wrapper, so no local Gradle install is required:
+
+```sh
+./gradlew build
+```
+
+## Running
+
+Start the REPL:
+
+```sh
+./gradlew run
+```
+
+Run a program file:
+
+```sh
+./gradlew run --args="examples/fib.lumen"
+```
+
+Disassemble the compiled bytecode for a file:
+
+```sh
+./gradlew run --args="--dump examples/fib.lumen"
+```
+
+## Example
+
+```lumen
+fn makeCounter() {
+    var count = 0
+    fn increment() {
+        count = count + 1
+        return count
+    }
+    return increment
+}
+
+let counter = makeCounter()
+println(counter(), counter(), counter())
+
+let numbers = [1, 2, 3, 4, 5]
+let doubled = map(fn(x) { return x * 2 }, numbers)
+println(doubled)
+```
+
+More programs live in [`examples/`](examples/), including a reverse-polish
+calculator, closures, sorting, CSV handling, and reusable library modules under
+`examples/lib/`.
+
+## Project layout
+
+```
+src/main/kotlin/lumen/
+  lexer/      token definitions and the tokenizer
+  ast/        abstract syntax tree nodes
+  parser/     recursive descent parser
+  bytecode/   opcodes, chunk container, and disassembler
+  compiler/   AST to bytecode compiler
+  runtime/    runtime value model
+  vm/         virtual machine, builtins, methods, and standard library
+  module/     module loader and import resolution
+  cli/        REPL and command-line entry point
+src/test/kotlin/lumen/   test suite
+examples/                sample Lumen programs
+```
+
+## Tests
+
+```sh
+./gradlew test
+```