From afa24f5b7a3f52a173602c8cf67d24a482d0020e Mon Sep 17 00:00:00 2001
From: Daniel Henry <iamdanhenry@gmail.com>
Date: Thu, 21 Aug 2025 16:31:18 -0500
Subject: [PATCH] Add README.md

Signed-off-by: Daniel Henry <iamdanhenry@gmail.com>
---
 README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e50bc18
--- /dev/null
+++ b/README.md
@@ -0,0 +1,57 @@
+# clox — Crafting Interpreters (clox, C)
+
+A tiny bytecode VM + compiler for the Lox language, built while following *Crafting Interpreters*. This is a personal learning project.  
+**Status:** up through Chapter 14 (“Chunks of Bytecode”).
+
+## Build
+
+Requires a C99 compiler (tested with `clang` on macOS). Uses the provided Makefile.
+
+```sh
+# Build the executable to bin/clox
+make
+
+# Clean build artifacts
+make clean
+
+# Show discovered sources/objects (diagnostic)
+make debug
+
+# (Optional) regenerate compile_commands.json for clangd/etc.
+make bear
+```
+
+## Run (current behavior)
+
+The current `main` builds a tiny test chunk and disassembles it—there’s no REPL or script runner yet.
+
+```sh
+./bin/clox
+```
+
+Example output:
+
+```
+== test chunk ==
+0000  123 OP_CONSTANT    0 '1.2'
+0002   | OP_RETURN
+```
+
+## Layout
+
+```
+include/   # headers
+src/       # .c files (chunk, value, memory, debug, main)
+obj/       # build objects (generated)
+bin/       # executable output (generated)
+```
+
+## Notes
+
+- Tracks the book’s **clox** implementation; commits may follow chapters.
+- `compile_commands.json` can be generated via `make bear` for editor tooling.
+
+## License
+
+Private / for learning.
+