From 12f831a9bce781b0d4e990fbda64b58e24491103 Mon Sep 17 00:00:00 2001
From: Donald Filimon <cbkshadow@icloud.com>
Date: Sun, 6 Jul 2025 10:06:43 -0400
Subject: [PATCH] Update README with build and usage instructions

---
 README.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 56 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index ac754df..cea09b9 100644
--- a/README.md
+++ b/README.md
@@ -4,19 +4,49 @@ This repository contains experimental implementations of the OuroLang programmin
 
 ## Building
 
+### Standalone Interpreter
+
 A simple C++ interpreter is provided in `ouro_lang.cc`. You can build it using g++:
 
 ```bash
 g++ -std=c++23 ouro_lang.cc -o ouro_lang
 ```
 
-Then run the REPL:
+### Running the REPL
+
+After building, start the interpreter REPL:
 
 ```bash
 ./ouro_lang
 ```
 
-A Zig build script is also included (`build.zig`) for environments with the Zig compiler installed.
+If built with CMake or Zig, binaries are placed in `build/` and `zig-out/bin`:
+
+```bash
+./build/ouro_lang         # from CMake
+./zig-out/bin/ourolang_repl  # from Zig
+```
+
+### CMake
+
+Configure and build all components with:
+
+```bash
+cmake -S . -B build
+cmake --build build
+```
+
+Executables will appear in `build/`. Use `./build/ouro_lang` to launch the REPL.
+
+### Zig
+
+A Zig build script (`build.zig`) is available:
+
+```bash
+zig build
+```
+
+Artifacts are placed under `zig-out/bin`. The REPL binary is `zig-out/bin/ourolang_repl`.
 
 ## Repository Structure
 
@@ -30,7 +60,30 @@ The `ouro_mod` directory showcases a minimal C++23 module setup. Build and run t
 zig build mod-run
 ```
 
-Run its tests using:
+## Running Examples
+
+The `Ouroboros` C lexer can process the sample programs in `Ouroboros/Ouroboros_Compiler/examples`:
+
+```bash
+zig build
+./zig-out/bin/ouroboros Ouroboros/Ouroboros_Compiler/examples/hello_world.ouro
+```
+
+You can also execute the modular C++ example with:
+
+```bash
+zig build mod-run
+```
+
+## Testing
+
+After building with CMake run the test suite:
+
+```bash
+cd build && ctest
+```
+
+Module tests can be executed via Zig:
 
 ```bash
 zig build mod-test