From 815f4a4725f6c84f6609815ebb5a4a33658e8265 Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Mon, 23 Feb 2026 02:25:46 +0300
Subject: [PATCH] docs: document using `just` in the codebase

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I56d1de8a88bb28e49e6387a320f318c86a6a6964
---
 README.md | 51 ++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 38 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 1048d9c..9ff280b 100644
--- a/README.md
+++ b/README.md
@@ -169,27 +169,44 @@ Entry:
 ### Building
 
 ```bash
-# Configure
-$ cmake -B build
+# Using just (recommended)
+$ just build
 
-# Build
-$ make
+# Or manually with CMake
+$ cmake -B build -G Ninja
+$ cmake --build build
 
-# The nix-irc executable will be in the project root
-$ ./nix-irc --help
+# The nix-irc executable will be in build/
+$ ./build/nix-irc --help
 ```
 
+### Available Tasks
+
+Run `just` to see all available tasks:
+
+- `just build` - Build all targets
+- `just test` - Run all tests (unit, compile, integration)
+- `just bench` - Run performance benchmarks
+- `just clean` - Clean build artifacts
+- `just smoke` - Run quick smoke test
+- `just stats` - Show project statistics
+
+See `just --list` for the complete list of available commands.
+
 ### Compiling Nix to IR
 
 ```bash
 # Basic compilation
-$ nix-irc input.nix output.nixir
+$ ./build/nix-irc input.nix output.nixir
 
 # With import search paths
-$ nix-irc -I ./lib -I /nix/store/... input.nix output.nixir
+$ ./build/nix-irc -I ./lib -I /nix/store/... input.nix output.nixir
 
 # Disable import resolution
-$ nix-irc --no-imports input.nix output.nixir
+$ ./build/nix-irc --no-imports input.nix output.nixir
+
+# Using just
+$ just compile input.nix output.nixir
 ```
 
 ### Runtime Evaluation (Plugin)
@@ -212,13 +229,21 @@ $ 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"
+# Run all tests
+$ just test
+
+# Run specific test suites
+$ just test-unit        # Unit tests only
+$ just test-compile     # Compilation tests only
+$ just test-integration # Integration tests only
+
+# Manually test all fixtures
+$ for f in tests/fixtures/*.nix; do
+    ./build/nix-irc "$f" "${f%.nix}.nixir"
 done
 
 # Verify IR format
-$ hexdump -C tests/simple.nixir | head -3
+$ hexdump -C tests/fixtures/simple.nixir | head -3
 ```
 
 ## Contributing