docs(nix): Explain how and why

nix/README.md

@@ -90,12 +90,20 @@ $ ./result/bin/atlantis
 $ ./result/bin/sorcerer
 ```
 
-## Dependencies
+### Update dependencies
 
-The build system automatically handles:
-- .NET SDK and runtime dependencies
-- JavaScript packages via Bun
-- Private NuGet packages from the Oceanbox registry
-- System libraries (NetCDF, etc.)
+When updating the `npm` dependencies, the `outputHash` in `atlantis-client.nix` needs to be updated. Simply run
 
-For updating dependencies, see the [scripts documentation](../scripts/README.md).
+```bash
+nix-build -A packages.atlantis-client # in the root
+```
+
+It will then fail on the wrong hash and provide the correct one.
+
+#### Deterministic builds, vendor hashes, and lock files
+
+Nix aims for deterministic (reproducible) builds. A key part of this is **fixed-output derivations (FODs)** such as `fetchurl`, `buildDotnetModule`’s vendor step, `fetchgit`, etc. For any FOD, Nix requires a **content hash** up front. After the build/fetch runs, Nix verifies that the resulting output’s hash exactly matches what was declared; if it doesn’t, the build fails with a “hash mismatch in fixed-output derivation” error. This protects you from drifting dependencies and ensures that CI and local builds use the exact same inputs.
+
+#### Why vendor hashes need to be pinned
+
+Language ecosystems resolve and download a lot of upstream content (Go modules, npm/yarn, cargo crates, vendored tarballs…). To make those fetches deterministic, Nix needs the **expected content hash**. For example, with `makeDerivation`, you must set `outputHash` so Nix knows what the fully-resolved module tree should hash to. If you bump a version or change dependencies, the **content changes** and the old hash becomes invalid—Nix will (correctly) refuse the build until you update the pinned hash.