docs: document binary format; add testing instructions

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I2cb3440f97b4add57860b212a60442336a6a6964

README.md

@@ -29,6 +29,19 @@ The plugin automatically chooses the fastest path based on file availability.
 
 ## Usage
 
+### Building
+
+```bash
+# Configure
+$ cmake -B build
+
+# Build
+$ make
+
+# The nix-irc executable will be in the project root
+$ ./nix-irc --help
+```
+
 ### Compiling Nix to IR
 
 ```bash
@@ -42,6 +55,54 @@ $ nix-irc -I ./lib -I /nix/store/... input.nix output.nixir
 $ nix-irc --no-imports input.nix output.nixir
 ```
 
+### Runtime Evaluation (Plugin)
+
+```bash
+# Load the plugin and evaluate IR
+$ nix --plugin-files ./nix-ir-plugin.so eval --expr 'builtins.nixIR_loadIR "output.nixir"'
+
+# On-the-fly compilation and evaluation
+$ nix --plugin-files ./nix-ir-plugin.so eval --expr 'builtins.nixIR_compile "1 + 2 * 3"'
+
+# Get plugin info
+$ nix --plugin-files ./nix-ir-plugin.so eval --expr 'builtins.nixIR_info'
+```
+
+### Running Tests
+
+```bash
+# Test all sample files
+for f in tests/*.nix; do
+    ./nix-irc "$f" "${f%.nix}.nixir"
+done
+
+# Verify IR format
+$ hexdump -C tests/simple.nixir | head -3
+```
+
+## IR Format
+
+The `.nixir` files use a versioned binary format:
+
+```plaintext
+Header:
+  - Magic: 0x4E495258 ("NIRX")
+  - Version: 1 (uint32)
+  - Source count: uint32
+  - Import count: uint32
+  - String table size: uint32
+
+String Table:
+  - Interned strings for efficient storage
+
+Nodes:
+  - Binary encoding of IR nodes
+  - Each node has type tag + inline data
+
+Entry:
+  - Main expression node index
+```
+
 ## Contributing
 
 This is a research/experimental project. Contributions welcome!