From 38807c927516c62009959d6c452dad1dc50743cc Mon Sep 17 00:00:00 2001
From: Donald Filimon <cbkshadow@icloud.com>
Date: Mon, 7 Jul 2025 09:40:36 -0400
Subject: [PATCH] docs: fix minor wording

---
 README.md            | 32 +++++++++++++++++++++++++++-----
 docs/architecture.md |  5 +++--
 docs/build_system.md | 21 +++++++++++++--------
 docs/contrib.md      |  3 ++-
 docs/testing.md      |  9 ++++-----
 5 files changed, 49 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index c2a3691..9cdecaf 100644
--- a/README.md
+++ b/README.md
@@ -4,23 +4,45 @@ This repository contains experimental implementations of the OuroLang programmin
 
 ## Building
 
-A simple C++ interpreter is provided in `ouro_lang.cc`. You can build it using g++:
+The recommended way to compile the project is via Zig:
 
 ```bash
-g++ -std=c++23 ouro_lang.cc -o ouro_lang
+zig build
+```
+
+This compiles the REPL and all supporting modules using C23/C++23 and links against LLVM. Run the modular demo with:
+
+```bash
+zig build mod-run
 ```
 
-Then run the REPL:
+Execute its unit tests using:
 
 ```bash
+zig build mod-test
+```
+
+If Zig is unavailable you can still build the simple interpreter directly:
+
+```bash
+g++ -std=c++23 ouro_lang.cc -o ouro_lang
 ./ouro_lang
 ```
 
-A Zig build script is also included (`build.zig`) for environments with the Zig compiler installed.  It now compiles the C portions of the project using the C23 standard and links against LLVM in addition to `libc`. The script mirrors the basic CMake configuration and exposes tasks for running the module example and its unit tests.
+Legacy CMake files remain for compatibility and can be used instead of Zig:
+
+```bash
+mkdir build && cd build
+cmake ..
+cmake --build . -- -j\$(nproc)
+```
 
 ## Repository Structure
 
-The project now includes a CMake-based build system, tests, container setup, and documentation. Run `cmake` in a `build` directory to configure and build the modules in `src/`.
+The source tree contains C and C++ code alongside a `build.zig` script.
+Zig's build system is used to compile the interpreter and modules.  A
+CMake configuration is kept in `cmake/` for environments that still
+depend on it.
 
 ## Zig Build with Modules
 
diff --git a/docs/architecture.md b/docs/architecture.md
index b264cb1..527c0bb 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -9,5 +9,6 @@ components.  The current prototype focuses on:
 * a REPL front-end built on top of the interpreter so language
   features can be exercised interactively
 
-Future iterations will replace the experimental pieces with a modular
-pipeline written in modern C++23 with optional Zig build integration.
+The project is now driven by Zig's build system which compiles the
+C and C++23 components. Future iterations will continue to evolve this
+modular pipeline while keeping Zig at the centre of the build process.
diff --git a/docs/build_system.md b/docs/build_system.md
index 9389714..242e4b8 100644
--- a/docs/build_system.md
+++ b/docs/build_system.md
@@ -1,17 +1,13 @@
 # Build System
 
-The repository can be built using vanilla CMake or the Zig build
-script.  Typical CMake usage:
+The repository uses Zig's build system by default. Simply run
 
 ```bash
-mkdir build && cd build
-cmake ..
-cmake --build . -- -j$(nproc)
-ctest --output-on-failure
+zig build
 ```
 
-The Zig file `build.zig` mirrors the above configuration and also
-exposes custom steps for running the module demo:
+to compile the interpreter and supporting modules. Additional steps
+are available for the module demo:
 
 ```bash
 zig build mod-run
@@ -20,3 +16,12 @@ zig build mod-test
 
 No external dependencies are required; all modules are built from the
 checked-in sources.
+
+If Zig is unavailable, a CMake configuration remains:
+
+```bash
+mkdir build && cd build
+cmake ..
+cmake --build . -- -j\$(nproc)
+ctest --output-on-failure
+```
diff --git a/docs/contrib.md b/docs/contrib.md
index 1a0e2ce..5c46f9d 100644
--- a/docs/contrib.md
+++ b/docs/contrib.md
@@ -1,7 +1,8 @@
 # Contributing
 
 We welcome pull requests that improve the interpreter, documentation or
-build system.  Please keep patches small and ensure `ctest` passes.
+build system.  Please keep patches small and ensure `zig build mod-test`
+passes.
 
 Steps for new contributors:
 
diff --git a/docs/testing.md b/docs/testing.md
index b39056c..76f0c4d 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -5,11 +5,10 @@ fuzzing harness.
 
 ### Unit tests
 
-```
-mkdir build && cd build
-cmake ..
-cmake --build .
-ctest --output-on-failure
+Run the small suite of module tests with Zig:
+
+```bash
+zig build mod-test
 ```
 
 ### Fuzzing