diff --git a/docs/rust.md b/docs/rust.md
new file mode 100644
index 0000000..9a884bc
--- /dev/null
+++ b/docs/rust.md
@@ -0,0 +1,197 @@
+# Writing Rust-backed opcodes for Fun VM
+
+This guide explains how to implement VM opcodes in Rust, wire them into the C VM, and use them from Fun scripts.
+
+It assumes you are comfortable with basic Rust and C and have a working Fun checkout.
+
+## Overview
+
+Fun’s VM is written in C, but you can implement opcode handlers in Rust and call them via FFI. The typical flow is:
+
+1) Write a Rust function with a stable C ABI (extern "C", #[no_mangle]) that takes a pointer to the VM and returns an int status code.
+2) Use VM stack helpers (exposed to Rust via FFI) to pop arguments and push results.
+3) Expose that Rust function to the C VM by calling it from the opcode dispatch (a case in the VM’s opcode switch or a small shim under src/vm/rust/).
+4) Add or reuse a Fun builtin that maps to your opcode, then call it from Fun code.
+
+## Project layout (relevant parts)
+
+- src/rust/src/lib.rs — Rust library with exported opcode functions and FFI helpers.
+- src/vm/rust/ — C-side wiring examples and small opcode cases calling into Rust.
+- examples/rust_hello.fun — Example Fun script using a Rust-backed opcode.
+- docs/opcodes.md — General overview of many built-in opcodes (mostly C-based).
+
+## Enabling Rust in the build
+
+Rust integration is optional and gated by a CMake flag. Default builds usually have it OFF.
+
+Enable it for a configured profile (Debug or Release):
+
+- Debug example:
+  cmake -S . -B build_debug -DFUN_WITH_RUST=ON
+  cmake --build build_debug --target fun
+
+- Release example:
+  cmake -S . -B build_release -DFUN_WITH_RUST=ON
+  cmake --build build_release --target fun
+
+Useful targets in this repository include:
+- fun — the main executable
+- rust_ops_build — helps build/link Rust ops when enabled
+- test_opcodes — test executable (if you want to extend tests)
+
+Note: In CLion, prefer building with one of the provided CMake profiles (Debug/Release) and avoid creating custom build directories.
+
+## Writing an opcode in Rust
+
+The Rust side is a no_std static library exposing C ABI functions that the VM can call. See src/rust/src/lib.rs for examples already in the tree.
+
+Key points:
+- Use extern "C" and #[no_mangle] to fix the symbol name.
+- Take a raw pointer to the VM as *mut Vm; return i32 status (0 for success).
+- Interact with the VM stack via helper FFI functions declared as externs.
+- Provide a minimal panic handler (no_std) as shown in lib.rs.
+
+Example: integer addition opcode implemented in Rust.
+
+In src/rust/src/lib.rs:
+
+    #![no_std]
+
+    #[repr(C)]
+    pub struct Vm;
+
+    extern "C" {
+        fn vm_pop_i64(vm: *mut Vm) -> i64;
+        fn vm_push_i64(vm: *mut Vm, v: i64);
+    }
+
+    #[no_mangle]
+    pub extern "C" fn fun_op_radd(vm: *mut Vm) -> i32 {
+        unsafe {
+            let b = vm_pop_i64(vm);
+            let a = vm_pop_i64(vm);
+            vm_push_i64(vm, a + b);
+        }
+        0
+    }
+
+    #[panic_handler]
+    fn panic(_info: &core::panic::PanicInfo) -> ! { loop {} }
+
+What this does:
+- Pops two 64-bit integers from the VM stack.
+- Pushes back their sum.
+- Returns 0 to indicate success to the VM.
+
+You can add more extern helpers (e.g., for strings, arrays, maps) once they are exposed by the C VM. The repository already includes a simple string example returning a const char* from Rust, see fun_rust_get_string() usage below.
+
+## Wiring the opcode in C
+
+To make the VM call your Rust opcode, add a small C-side case that invokes the exported Rust symbol. A minimal pattern lives under src/vm/rust/.
+
+String demo wiring (already present): src/vm/rust/hello.c
+
+    case OP_RUST_HELLO: {
+    #ifdef FUN_WITH_RUST
+        const char *s = fun_rust_get_string();
+        if (!s) s = "";
+        push_value(vm, make_string(s));
+    #else
+        vm_raise_error(vm, "RUST_HELLO requires FUN_WITH_RUST=ON at build time");
+        push_value(vm, make_nil());
+    #endif
+        break;
+    }
+
+For a stack-based math opcode (like fun_op_radd), you would declare and call the Rust function similarly:
+
+    #ifdef FUN_WITH_RUST
+    extern int fun_op_radd(void* vm); // or use the proper VM type if available
+    #endif
+
+    case OP_RADD: {
+    #ifdef FUN_WITH_RUST
+        (void)fun_op_radd(vm);
+    #else
+        vm_raise_error(vm, "RADD requires FUN_WITH_RUST=ON at build time");
+        push_value(vm, make_nil()); // or follow your opcode’s error convention
+    #endif
+        break;
+    }
+
+Notes:
+- Follow the existing opcode conventions for your module (core, math, strings, etc.).
+- If your build puts the Rust symbol into a static library, make sure the VM target links it when FUN_WITH_RUST is ON (the top-level CMake already does this for the examples provided).
+
+## Using Rust-backed opcodes from Fun
+
+Once wired, expose the opcode via a builtin function or directly in bytecode. The repository includes a demo builtin rust_hello() that returns a Rust-generated string.
+
+Run the example:
+
+1) Build with Rust enabled (Debug):
+   cmake -S . -B build_debug -DFUN_WITH_RUST=ON
+   cmake --build build_debug --target fun
+
+2) Execute the script:
+   build_debug/fun examples/rust_hello.fun
+
+Expected output:
+   Hello from Rust ops!
+
+If you build without Rust, calling rust_hello() raises a runtime error indicating that Rust integration is disabled.
+
+## Stack discipline and error handling
+
+- Always pop exactly the arguments you expect and push exactly the results your opcode promises. Mismatch leads to stack corruption and hard-to-debug failures.
+- Return an int status to the VM (0 for success). If your project uses a different convention for some opcodes, match it consistently.
+- Validate types where appropriate (e.g., ensure values are integers before arithmetic). If a check fails, use the VM’s error mechanism (e.g., vm_raise_error) and follow the module’s convention on what to push after errors.
+
+## Data types and FFI surface
+
+The minimal helpers shown cover 64-bit integers and simple strings. Extending the Rust<->C bridge usually involves:
+- Declaring additional extern "C" functions in Rust that the C VM implements (to read/write values on the stack, construct arrays/maps/strings, etc.).
+- Ensuring all pointers and lifetimes are well-defined: strings pushed to the VM should be copied or allocated using VM facilities so they remain valid after the call.
+- Keeping Rust no_std unless you add an allocator and link setup to support std.
+
+## Troubleshooting
+
+- Link errors: Make sure FUN_WITH_RUST=ON for your build directory and that the Rust library is compiled before linking the VM. Use the rust_ops_build target if provided by your profile.
+- Missing symbol at runtime: Confirm #[no_mangle] and extern "C" on the Rust function and that C sees the correct prototype.
+- Wrong or garbled values: Double-check stack order (Fun uses a stack VM; many ops pop in reverse order: first b, then a).
+- No output from rust_hello(): Ensure you run a binary built with FUN_WITH_RUST=ON; otherwise the VM deliberately raises an error and returns Nil for that call.
+
+## Small end-to-end checklist
+
+1) Write the Rust function in src/rust/src/lib.rs with extern "C", #[no_mangle].
+2) Use FFI helpers to pop arguments and push results.
+3) Add a C-side case under src/vm/... (or src/vm/rust/...) that calls your Rust function when the opcode executes.
+4) Ensure the build links Rust code when FUN_WITH_RUST=ON.
+5) Add or reuse a builtin in the parser/runtime to surface your opcode to Fun code.
+6) Build and run a small .fun example to validate behavior.
+
+## References in this repo
+
+- Rust lib with examples: src/rust/src/lib.rs
+- C-side hello wiring: src/vm/rust/hello.c
+- Demo script: examples/rust_hello.fun
+- General opcode reference: docs/opcodes.md
+
+## Links
+
+Authoritative and practical resources on exposing Rust to C (FFI) and maintaining a C-compatible API:
+
+- Rustonomicon: FFI overview and best practices
+  https://doc.rust-lang.org/nomicon/ffi.html
+- Rustonomicon: Calling Rust code from C
+  https://doc.rust-lang.org/nomicon/ffi.html#calling-rust-code-from-c
+- The Rust Book: Unsafe and FFI (extern, #[no_mangle], calling Rust from other languages)
+  https://doc.rust-lang.org/book/ch19-01-unsafe-rust.html#calling-rust-functions-from-other-languages
+- Rust Reference: extern blocks, ABIs, and linkage
+  https://doc.rust-lang.org/reference/items/external-blocks.html
+- Rust FFI Omnibus (examples for many patterns, including Rust ↔ C)
+  https://github.com/shepmaster/rust-ffi-omnibus
+- cbindgen (generate C headers from Rust libraries)
+  https://cbindgen.github.io/cbindgen/
+- bindgen (generate Rust bindings to existing C headers; useful when mixing C and Rust)
+  https://github.com/rust-lang/rust-bindgen
diff --git a/examples/features.fun b/examples/features.fun
old mode 100644
new mode 100755
diff --git a/examples/rust_hello.fun b/examples/rust_hello.fun
old mode 100644
new mode 100755