docs: initial project overview

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

README.md

@@ -0,0 +1,54 @@
+# Nixir - Import-Resolving IR Plugin
+
+Nixir, for the lack of a more imaginative name, is a Nix plugin with a fancy
+hybrid compilation architecture for optimized evaluation. We provide two
+complementary paths for Nix evaluator. It is either **On-the-fly compilation**
+where the plugin parses and compiles Nix code at runtime, or; **ahead-of-time**
+compilation where the `nix-irc` tool pre-compiles `.nix` files into `.nixir`
+files.
+
+The plugin automatically chooses the fastest path based on file availability.
+
+## Supported Nix Constructs
+
+- Literals: integers, strings, booleans, null, paths
+- Attrsets: `{ name: value; }`
+- Recursive attrsets: `rec { ... }`
+- Let bindings: `let x: 1; in x`
+- Recursion let: `let rec x: y; y: x; in x`
+- Conditionals: `if cond then a else b`
+- Lambdas: (basic support, patterns coming in Phase 5)
+- Applications: function calls
+- Selections: `attrset.attribute`
+- Assertions: `assert condition; expr`
+- With expressions: `with attrs; expr`
+- Operators:
+  - Binary: `+`, `-`, `*`, `/`, `++`, `==`, `!=`, `<`, `>`, `<=`, `>=`, `&&`,
+    `||`, `->`
+  - Unary: `-`, `!`
+
+## Usage
+
+### Compiling Nix to IR
+
+```bash
+# Basic compilation
+$ nix-irc input.nix output.nixir
+
+# With import search paths
+$ nix-irc -I ./lib -I /nix/store/... input.nix output.nixir
+
+# Disable import resolution
+$ nix-irc --no-imports input.nix output.nixir
+```
+
+## Contributing
+
+This is a research/experimental project. Contributions welcome!
+
+Areas where help is needed:
+
+- Expanding parser to handle more Nix syntax
+- Performance optimization
+- Test coverage
+- Documentation improvements