sts2-bot/docs/DEVELOPMENT.md

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:

programs.direnv = {
  enable = true;
  nix-direnv.enable = true;
};

Ensure your interactive shell has the direnv hook enabled. Then, in the repository:

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:

nix develop

Offline checks

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:

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. 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.