# Mod source and Linux setup

The bot pins its STS2MCP fork as a Git submodule at `vendor/STS2MCP`.
The fork is private: your desktop needs SSH access to `git.rasyidanaf.com`.
The upstream project and its MIT license remain in the submodule.

## Get both repositories

For a new checkout:

```sh
git clone --recurse-submodules git@git.rasyidanaf.com:0xrsydn/sts2-bot.git
cd sts2-bot
```

For an existing checkout:

```sh
git pull --ff-only
git submodule sync --recursive
git submodule update --init --recursive
```

An old, unmanaged `vendor/STS2MCP` directory can block initialization. Preserve any
local changes by moving that directory outside the checkout before initializing.
Do not delete it blindly. Do not use `git submodule update --remote` for normal
setup: that bypasses the revision tested with this bot.

Jujutsu does not populate submodule working trees. After a `jj` checkout/update,
use `git submodule update --init --recursive` in a colocated repository. Submodule
revision changes require Git; ordinary bot changes can continue to use `jj`.

## Build on CachyOS / Linux

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.

From the bot repository root:

```sh
GAME_DIR="$HOME/.local/share/Steam/steamapps/common/Slay the Spire 2"
test -f "$GAME_DIR/data_sts2_linuxbsd_x86_64/sts2.dll"
dotnet build vendor/STS2MCP/STS2_MCP.csproj -c Release \
  -p:STS2GameDir="$GAME_DIR" -o /tmp/sts2-mcp-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.

## Install with the game closed

Back up existing files before replacing them:

```sh
MODS_DIR="$GAME_DIR/mods"
BACKUP_DIR="$HOME/.local/state/sts2-bot/mod-backups/$(date +%Y%m%dT%H%M%S)"
mkdir -p "$MODS_DIR" "$BACKUP_DIR"
for file in STS2_MCP.dll STS2_MCP.json; do
  if [ -f "$MODS_DIR/$file" ]; then cp -p "$MODS_DIR/$file" "$BACKUP_DIR/"; fi
done
cp /tmp/sts2-mcp-build/STS2_MCP.dll "$MODS_DIR/STS2_MCP.dll"
cp vendor/STS2MCP/mod_manifest.json "$MODS_DIR/STS2_MCP.json"
```

Do not use the historical DLL files in the bot's `vendor/` root. They predate
this API extension. Keep configuration files and other mods unchanged.
Launch the game through Steam and accept mod loading if prompted.

Read-only health check:

```sh
curl --fail --silent --show-error 'http://localhost:15526/api/v1/singleplayer?format=json'
```

At the main menu, no player/deck/reward data is expected. In a run, inspect
`player.permanent_deck`. On a card reward screen, inspect
`card_reward.alternatives`. Do not expose the unauthenticated local API publicly.

## Current integration limits

The mod extension builds and passed isolated action-guard tests. On macOS, loading
and a main-menu GET were verified. Live deck/alternative serialization and Linux
execution still require verification. The bot does not yet consume the new fields.
Composite scoring remains opt-in; automatic composite skipping is not implemented.

See the submodule's `docs/reward-observations.md` for the API contract and
[the audit](research/16-reward-api-audit.md) for the remaining work.