build(dev): add pinned Nix and nix-direnv environments

docs/DEVELOPMENT.md

@@ -0,0 +1,69 @@
+# Nix development environment
+
+The repository provides a locked development shell for `x86_64-linux` and
+`aarch64-darwin`: the CachyOS desktop and Apple Silicon MacBook. The shell provides Python, .NET SDK 9, Git, Jujutsu, curl, and Bash.
+`flake.lock` pins the package source for both desktop and laptop.
+
+## nix-direnv
+
+Enable flakes in Nix and configure direnv plus nix-direnv in your user environment.
+The repository does not change your shell configuration. With Home Manager:
+
+```nix
+programs.direnv = {
+  enable = true;
+  nix-direnv.enable = true;
+};
+```
+
+Ensure your interactive shell has the direnv hook enabled. Then, in the repository:
+
+```sh
+direnv allow
+```
+
+The checked-in `.envrc` calls `use flake`. Review it before allowing it.
+`.direnv/` is ignored. No credentials are loaded by `.envrc`.
+The first activation can download substantial SDK dependencies.
+
+Without direnv:
+
+```sh
+nix develop
+```
+
+## Offline checks
+
+```sh
+nix flake check -L
+```
+
+This runs the three Python regression scripts, dataset integrity checks, and Bash
+syntax checks. The check uses an isolated home and explicit source inputs. It
+needs no game, credentials, model calls, or submodule checkout. It does not rebuild
+the dataset. Nix can download dependencies before the offline check starts.
+
+For interactive checks in the shell:
+
+```sh
+python3 test_facts.py && python3 test_brain.py && python3 test_run.py
+python3 migrate.py --check-only
+bash -n eval_batch.sh ab_card_skip.sh
+```
+
+The flake does not build or launch the game. Build the mod inside `nix develop`
+or the direnv shell, using the local game path described in [MOD_SETUP.md](MOD_SETUP.md).
+Proprietary game assemblies remain outside the Nix store. The private mod submodule
+requires separate Git/SSH access, but the development shell does not fetch it.
+
+Live bot execution still needs the local mod API and separately configured model
+credentials. `--dry-run` can make model calls; it is not an offline test.
+
+## Updating packages
+
+Run `nix flake update nixpkgs`, then repeat the offline checks and mod build.
+Review and commit the lock-file update deliberately. Do not update dependencies
+merely to enter the shell.
+
+The outputs support the listed systems, but a successful macOS check does not
+prove Linux game integration. Run `nix flake check -L` on CachyOS too.