modified: CONTRIBUTING.md

new file:   flake.lock
	new file:   flake.nix

CONTRIBUTING.md

@@ -28,6 +28,46 @@ HTTPS or localhost, because it uses the Origin Private File System.
 
 Windows from Linux: `cargo xwin build --release --target x86_64-pc-windows-msvc -p solvecraft`.
 
+### NixOS: `nix develop`
+
+NixOS has no `/usr/lib`, so nothing is on `LD_LIBRARY_PATH` and a plain `cargo run` finds none of
+the libraries the app loads at run time: the Wayland ones winit opens the window through, the EGL
+loader wgpu renders through, and libdbus-1, which rfd's file dialogs reach xdg-desktop-portal
+through (a dialog then never appears and the pick returns no path):
+
+```
+ERROR solvecraft: winit EventLoopError: ... The wayland library could not be loaded
+ERROR eframe::native::run: Exiting because of error: WGPU error: Failed to create surface for any enabled backend: {}
+ERROR rfd::backend::xdg_desktop_portal::portal::libdbus: Can't connect to a portal: libdbus-1.so not found
+```
+
+`nix develop` (the [`flake.nix`](flake.nix) in the repository root) puts the Wayland, X11,
+EGL-loader and D-Bus libraries on `LD_LIBRARY_PATH`, so `cargo run --release -p solvecraft` works
+from that shell as on any other distribution, file dialogs included. `nix run` builds the app and
+wraps the binary the same way. The Mesa drivers stay the system's, from `/run/opengl-driver`
+(`hardware.graphics.enable`): that is the driver stack the compositor runs on, and wgpu reaches the
+integrated GPU through the EGL loader. The shell deliberately brings no Rust toolchain — the one on
+`PATH` keeps its build cache, where a second `rustc` would make every build recompile the workspace
+from scratch; `nix develop .#rust` is there for a machine with no Rust at all.
+
+**Anti-aliasing on the OpenGL backend.** NixOS keeps the Vulkan ICD descriptions
+(`/run/opengl-driver/share/vulkan/icd.d`) off the Vulkan loader's search path, so wgpu picks its
+OpenGL backend on the integrated GPU. On that backend any multisampling above 1× — the default is
+4× — draws a black window: the UI still lays out and the control channel still answers, but every
+frame, `ui.screenshot` included, comes out empty. Set **Preferences ▸ Graphics ▸ Anti-aliasing** to
+1× and restart (the setting applies on the next start), or write it before the first run, since a
+black window is no way to reach the dialog:
+
+```sh
+mkdir -p ~/.local/share/solvecraft
+echo '{"msaa": 1}' > ~/.local/share/solvecraft/graphics.json
+```
+
+`apps/solvecraft/src/main.rs` reads that file (`graphics_path()`, eframe's storage dir) before the
+window opens; 2× and 4× are the same black window. The Vulkan backend is no way out of it either:
+`libvulkan.so.1` is not on `LD_LIBRARY_PATH`, so `WGPU_BACKEND=vulkan` exits with a
+`CreateSurfaceError` instead.
+
 ## How the code is laid out
 
 The [README](README.md#architecture) has the layer table. The short version: