From da9be4b014df0b5e0dcaf19b0fd97474e226c6f6 Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Sat, 21 Feb 2026 20:49:02 +0300
Subject: [PATCH] docs: document binary format; add testing instructions

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I2cb3440f97b4add57860b212a60442336a6a6964
---
 README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/README.md b/README.md
index 25cf524..e99dc1e 100644
--- a/README.md
+++ b/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!