From 73a92b26b6f6a2dd01734945e13beab60eb955d8 Mon Sep 17 00:00:00 2001
From: _cry64 <them@dobutterfliescry.net>
Date: Sat, 11 Apr 2026 10:27:07 +1000
Subject: [PATCH] update README

---
 README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f40390a..0d21708 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,68 @@
-# nixide
+![enbyware](https://pride-badges.pony.workers.dev/static/v1?label=enbyware&labelColor=%23555&stripeWidth=8&stripeColors=FCF434%2CFFFFFF%2C9C59D1%2C2C2C2C)
+![repo size](https://img.shields.io/github/repo-size/cry128/nixide)
 
-rust wrapper for libnix :3
\ No newline at end of file
+# ❄️ nixide ❄️
+
+<p align="center">Because Nix never held your hand. It shot off your fingers and spat out God's longest stack trace</p>
+
+Never have I longed for a coup de grâce more than my attempts at using the `libnix` APIs.
+*C++ isn't real and it can't hurt you...* Nixide is cheaper than therapy and provides a completely
+redesigned approach to interacting with the Nix API. These aren't just bindings to `libnix`, I've gone through and
+redesigned error handling, simplified all provided interfaces, and written custom C++ extensions to expose
+internal features `libnix-c` could only dream of!
+
+
+## 💛💜🖤 Usage
+
+Below is an example of how Nixide can be used to locally build a NixOS system
+from a `flake.nix` and remotely deploy it. This is **not** an easy thing
+to do with the `libnix` API by default. 
+
+```rs
+use nixide::*;
+
+fn main() -> Result<(), NixideError> {
+    // open the default store: `/nix/store`
+    let storeref = Store::default()?;
+
+    // initialise the Nix evaluator with default settings
+    let eval_state = EvalState::default(storeref)?;
+
+    // get a flake reference to `/etc/nixos/flake.nix`
+    let flakeref = FlakeRefBuilder::new("/etc/nixos", eval_state)
+        .allow_dirty(true)
+        .warn_dirty(true)
+        .build()?;
+
+    // lock the flake and build the system configuration
+    let out_path: StorePath = flakeref
+        .lock()?
+        .outputs()?
+        .assert_type(NixType::Attrs)?
+        .get("nixosConfigurations.MY_HOSTNAME")
+        .map(|system: NixThunk| {
+            system
+                .force_eval()?
+                .assert_type(NixType::Path)?
+                .into_store_path()
+        })
+        .expect("Flake does not provide `MY_HOSTNAME`")?;
+
+    // copy the local build to a remote system
+    // NOTE: this assumes an ssh-agent can supply a key for us, otherwise
+    // NOTE: use the syntax: `ssh://dobutterfliescry.net?ssh-key=/path/to/my/key`
+    let remote_storeref = Store::open("ssh://dobutterfliescry.net")?;
+    
+    out_path
+      .copy_closure_to(remote_storeref)?;
+      .as_nixos_system()?
+      .set_boot_target()?
+      .activate()?;
+}
+```
+
+## Credits
+
+Thanks so much to [@NotAShelf](https://github.com/NotAShelf) for maintaining their [nix-bindings](https://github.com/NotAShelf/nix-bindings) repository.
+And especially [RObert Hensing](https://github.com/roberth) and the [nixops4 team](https://github.com/nixops4) for their [nix-bindings-rust](https://github.com/nixops4/nix-bindings-rust) repository.
+Both of which I use extensively as reference when designing Nixide.