Update README.md

README.md

@@ -6,4 +6,43 @@ SPDX-License-Identifier: GPL-3.0-or-later
 
 # Chloride
 
-An Argon interpreter written in C
+Chloride is the new C-based interpreter for the Argon programming language.  
+It is designed as a drop-in replacement for the older Go implementation (argon-v3), while introducing a more efficient runtime and a cleaner, more consistent object model.
+
+## Overview
+
+Chloride aims to remain as interchangeable with argon-v3 as possible.  
+Most existing Argon code should run with minimal or no changes, and backwards compatibility is an ongoing priority.  
+Where behaviour differs, the goal is for those differences to be predictable and well-defined rather than accidental quirks.
+
+This interpreter replaces argon-v3's AST-walking runtime with a proper bytecode compiler, caching system, and virtual machine.  
+The result is a more consistent execution model, lower memory usage, and improved overall performance, even though speed is not the sole focus of the project.
+
+## Key Improvements Over argon-v3
+
+- **Bytecode + VM architecture**  
+  Chloride compiles source code into bytecode and executes it through a dedicated virtual machine.  
+  The previous interpreter evaluated the AST directly at runtime, which limited performance and made optimisations difficult.
+
+- **Reduced memory usage and CPU overhead**  
+  Chloride is written in C with an emphasis on minimal allocations, predictable lifetimes, and efficient object handling.
+
+- **Unified object model**  
+  In contrast to argon-v3, where some values (such as numbers) were not objects, Chloride treats every value as a first-class object.  
+  This simplifies the runtime and ensures a more consistent behaviour across all types.
+
+- **Proper class and inheritance system**  
+  Classes in Chloride are real objects, supporting inheritance and introspection in a clean, well-defined manner.  
+  The old interpreter treated classes as a special-case construct, which restricted the language's expressiveness.
+
+- **Backwards compatibility focus**  
+  Chloride aims to match argon-v3’s behaviour closely enough that most existing Argon programs run unchanged.  
+  Compatibility fixes and behavioural parity are treated as long-term goals.
+
+## Project Goals
+
+- Maintain high compatibility with argon-v3.  
+- Minimise memory usage and improve runtime efficiency.  
+- Provide a stable, maintainable interpreter core.  
+- Keep the implementation straightforward so that future language features can be built cleanly on top of it.  
+- Serve as the reference interpreter for Argon going forward.