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.

docs/MOD_SETUP.md

@@ -32,7 +32,9 @@ revision changes require Git; ordinary bot changes can continue to use `jj`.
 
 ## Build on CachyOS / Linux
 
-Install .NET SDK 9 and the native Linux Steam version of Slay the Spire 2.
+Enter the pinned development environment with `direnv allow` (nix-direnv) or
+`nix develop`. It includes .NET SDK 9; see [DEVELOPMENT.md](DEVELOPMENT.md).
+Install the native Linux Steam version of Slay the Spire 2 separately.
 Check that `dotnet --list-sdks` lists a 9.x SDK. Set `GAME_DIR` to the actual Steam
 library path; custom libraries and Flatpak Steam use different paths.
 
@@ -45,8 +47,8 @@ dotnet build vendor/STS2MCP/STS2_MCP.csproj -c Release \
   -p:STS2GameDir="$GAME_DIR" -o /tmp/sts2-mcp-build
 ```
 
-If you already use Nix, you can replace `dotnet build` with
-`nix shell nixpkgs#dotnet-sdk_9 --command dotnet build`.
+Outside the shell, prefix the build command with `nix develop --command`.
+This uses the repository lock file rather than your machine's nixpkgs registry.
 Build against your installed game assemblies. A successful Mac build does not
 prove compatibility with a different Linux game version.