diff --git a/docs/MOD_SETUP.md b/docs/MOD_SETUP.md
new file mode 100644
index 0000000..00854cb
--- /dev/null
+++ b/docs/MOD_SETUP.md
@@ -0,0 +1,90 @@
+# 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
+
+Install .NET SDK 9 and the native Linux Steam version of Slay the Spire 2.
+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
+```
+
+If you already use Nix, you can replace `dotnet build` with
+`nix shell nixpkgs#dotnet-sdk_9 --command dotnet build`.
+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.