build(nix): add flake

.gitignore

@@ -1,4 +1,6 @@
 /target
+/result
 
 /.tinyharness
-/todo
+/todo
+

README.md

@@ -59,6 +59,30 @@ Alternatively, install via Cargo:
 cargo install --path .
 ```
 
+### Installation (Nix)
+
+A Nix flake is provided for reproducible builds and dev environments.
+
+**Run once without installing:**
+
+```bash
+nix run github:PTFOPlayer/TinyHarness
+```
+
+**Build the package:**
+
+```bash
+cd TinyHarness
+nix build
+./result/bin/tinyharness
+```
+
+**Enter a development shell** (with Rust toolchain, rustfmt, and clippy pre-configured):
+
+```bash
+nix develop
+```
+
 ### Usage
 
 **Ollama** (default):
@@ -420,6 +444,14 @@ cargo fmt --all -- --check     # Format check
 cargo fmt --all                # Auto-format
 ```
 
+If you're using the Nix flake, prefer:
+
+```bash
+nix build                      # Build the package
+nix flake check                # Run all checks (build + fmt + clippy --deny warnings + test)
+nix develop                    # Enter dev shell with cargo/rustfmt/clippy
+```
+
 ### Verification Steps
 
 After making changes, run:

docs/contributing.md

@@ -6,7 +6,7 @@ TinyHarness is a Rust workspace with three crates and a focus on minimal depende
 
 ### Prerequisites
 
-- Rust latest stable (edition 2024)
+- Nix with flakes enabled or Rust latest stable (edition 2024)
 - An LLM backend for testing (Ollama recommended, but not required for library tests)
 
 ### Getting the Code
@@ -18,6 +18,9 @@ cd TinyHarness
 
 ### First Build
 
+>[!NOTE]
+>If you have Nix, run `nix develop`
+
 ```bash
 cargo build --workspace
 cargo test --workspace
@@ -117,6 +120,14 @@ Before submitting a PR, run these in order:
 3. `cargo test --workspace` — all tests pass
 4. `cargo build` — clean debug build succeeds
 
+If you have Nix installed, the same checks are available as a single command:
+
+```bash
+nix flake check
+```
+
+This runs `cargo fmt --all -- --check`, `cargo clippy --workspace -- -D warnings`, `cargo test --workspace` (release), and a release build — i.e. steps 1, 2, 3, and a release variant of step 4. See the [Nix installation section](../../README.md#installation-nix) in the README for setup.
+
 ---
 
 ## Code Conventions

flake.nix

@@ -0,0 +1,94 @@
+{
+  description = "TinyHarness - AI Coding Harness";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+    crane = {
+      url = "github:ipetkov/crane";
+    };
+    rust-overlay = {
+      url = "github:oxalica/rust-overlay";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs = { self, nixpkgs, flake-utils, crane, rust-overlay, ... }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        pkgs = import nixpkgs {
+          inherit system;
+          overlays = [ (import rust-overlay) ];
+        };
+
+        inherit (pkgs) lib;
+
+        rustToolchain = pkgs.rust-bin.stable.latest.default.override {
+          extensions = [ "rustfmt" "clippy" ];
+        };
+
+        craneLib = (crane.mkLib pkgs).overrideToolchain rustToolchain;
+
+        src = lib.cleanSourceWith {
+          filter = path: type:
+            (craneLib.filterCargoSources path type) ||
+            (lib.hasSuffix ".md" path);
+          src = lib.cleanSource ./.;
+        };
+
+        commonArgs = {
+          inherit src;
+          strictDeps = true;
+          buildInputs = [
+            pkgs.openssl
+          ] ++ lib.optionals pkgs.stdenv.isDarwin [
+            pkgs.apple-sdk
+          ];
+          nativeBuildInputs = [
+            pkgs.pkg-config
+          ];
+        };
+
+        cargoArtifacts = craneLib.buildDepsOnly commonArgs;
+
+        tinyharness = craneLib.buildPackage (commonArgs // {
+          inherit cargoArtifacts;
+          doCheck = false;
+          meta = {
+            mainProgram = "tinyharness";
+          };
+        });
+
+        tests = craneLib.cargoTest (commonArgs // {
+          inherit cargoArtifacts;
+        });
+
+      in {
+        packages = {
+          default = tinyharness;
+          tinyharness = tinyharness;
+        };
+
+        checks = {
+          inherit tinyharness;
+          inherit tests;
+          clippy = craneLib.cargoClippy (commonArgs // {
+            inherit cargoArtifacts;
+            cargoClippyExtraArgs = "-- --deny warnings";
+          });
+          fmt = craneLib.cargoFmt {
+            inherit src;
+          };
+        };
+
+        devShells.default = craneLib.devShell {
+          checks = self.checks.${system};
+          packages = with pkgs; [
+            cargo
+            clippy
+            rust-analyzer
+            rustfmt
+          ];
+        };
+      });
+}