improved docs and tools for embedding kotlin classes with properties

docs/embedding.md

@@ -109,7 +109,38 @@ scope.eval("val y = inc(41); log('Answer:', y)")
 
 You can register multiple names (aliases) at once: `addFn<ObjInt>("inc", "increment") { ... }`.
 
-### 5) Read variable values back in Kotlin
+### 5) Add Kotlin‑backed properties
+
+Properties in Lyng are pure accessors (getters and setters) and do not have automatic backing fields. You can add them to a class using `addProperty`.
+
+```kotlin
+val myClass = ObjClass("MyClass")
+var internalValue: Long = 10
+
+myClass.addProperty(
+    name = "value",
+    getter = { 
+        // Return current value as a Lyng object
+        ObjInt(internalValue) 
+    },
+    setter = { newValue ->
+        // newValue is passed as a Lyng object (the first and only argument)
+        internalValue = (newValue as ObjInt).value
+    }
+)
+
+scope.addConst("MyClass", myClass)
+```
+
+Usage in Lyng:
+```kotlin
+val instance = MyClass()
+println(instance.value) // -> 10
+instance.value = 42
+println(instance.value) // -> 42
+```
+
+### 6) Read variable values back in Kotlin
 
 The simplest approach: evaluate an expression that yields the value and convert it.
 
@@ -124,7 +155,7 @@ val kotlinName = scope.eval("name").toKotlin(scope) // -> "Lyng rocks!"
 
 Advanced: you can also grab a variable record directly via `scope.get(name)` and work with its `Obj` value, but evaluating `"name"` is often clearer and enforces Lyng semantics consistently.
 
-### 6) Execute scripts with parameters; call Lyng functions from Kotlin
+### 7) Execute scripts with parameters; call Lyng functions from Kotlin
 
 There are two convenient patterns.
 
@@ -157,7 +188,7 @@ val result = resultObj.toKotlin(scope) // -> 42
 
 If you need to pass complex data (lists, maps), construct the corresponding Lyng `Obj` types (`ObjList`, `ObjMap`, etc.) and pass them in `Arguments`.
 
-### 7) Create your own packages and import them in Lyng
+### 8) Create your own packages and import them in Lyng
 
 Lyng supports packages that are imported from scripts. You can register packages programmatically via `ImportManager` or by providing source texts that declare `package ...`.
 
@@ -212,7 +243,7 @@ val s = scope.eval("s").toKotlin(scope) // -> 144
 
 You can also register from parsed `Source` instances via `addSourcePackages(source)`.
 
-### 8) Executing from files, security, and isolation
+### 9) Executing from files, security, and isolation
 
 - To run code from a file, read it and pass to `scope.eval(text)` or compile with `Compiler.compile(Source(fileName, text))`.
 - `ImportManager` takes an optional `SecurityManager` if you need to restrict what packages or operations are available. By default, `Script.defaultImportManager` allows everything suitable for embedded use; clamp it down in sandboxed environments.
@@ -223,7 +254,7 @@ You can also register from parsed `Source` instances via `addSourcePackages(sour
 val isolated = net.sergeych.lyng.Scope.new()
 ```
 
-### 9) Tips and troubleshooting
+### 10) Tips and troubleshooting
 
 - All values that cross the boundary must be Lyng `Obj` instances. Convert Kotlin values explicitly (e.g., `ObjInt`, `ObjReal`, `ObjString`).
 - Use `toKotlin(scope)` to get Kotlin values back. Collections convert to Kotlin collections recursively.