# Standalone setup

This repository is a Witcher 3 development tool, independent of any combat-model
project. The qualified native installation is Remastered 5.01, DX12, on Linux
with Steam/Proton and KDE KWin. Python help and evidence tooling work without a
running game. Native control requires the matching installed bridge and receipts.

## Existing host

The original checkout is `~/witcher3-devkit`; `~/.local/bin/w3dev` points to its
launcher. Upgraded worktrees can share its installation after the explicit state
migration below. Migration does not reinstall or deploy game files:

```sh
w3dev guide setup
w3dev doctor
w3dev verify
w3dev guide debugger
w3dev commands --json
```

These commands do not launch or contact the game. Use `debug open` when ready to
launch with automatic lab settings; `debug close` performs the normal restoration.
Read the debugger guide before recovery or resuming a previous session.

## Source-only checkout

```sh
git clone https://tangled.org/io-streamer.bsky.social/witcher3-devkit
cd witcher3-devkit
./w3dev commands --json
./w3dev guide debugger
python3 -m unittest discover -s . -p 'test_*.py' -q
```

Python CLI/help/tests use the standard library. On a new host, place a symlink to
this checkout's `w3dev` in a directory on PATH if desired. Direct `./w3dev` and
`python3 /absolute/path/to/cli.py` require no registration or package installation.
User-supplied relative input/output paths resolve against the caller's directory;
paths in examples such as `plans/hag-pilot.json` assume this repository as CWD.

Configure a game installation using `local-config.example.json` as the format.
The default shared config is
`${XDG_CONFIG_HOME:-~/.config}/witcher3-devkit/local-config.json`.
A checkout-local ignored `local-config.json` remains a fallback when no shared
config exists. Schema version 1 permits only
`schema_version`, `game_directory` and `documents_directory`. Relative paths are
resolved against the config file, independent of the caller's working directory.

`W3DEV_CONFIG` takes precedence over shared and checkout-local configuration;
an explicitly selected missing file is
an error. `W3DEV_GAME` and `W3DEV_DOCUMENTS` override their respective config values.
Without config, defaults describe a conventional Linux Steam library and app
292030's Proton documents. Defaults are discovery hints, not proof of installation.
`doctor` shows the effective paths. Never change config during an active session.

Changing paths does not install, transfer ownership of, or qualify another build.
`install-native` and `install-ui` update an already-owned installation; there is
no general first-time installer. A new installation requires reviewed matching
native adapters, bridge/UI assets, dependency hashes and deployment receipts.
Do not copy another machine's receipts or invent hashes to bypass verification.

For an automatic Steam update, use `w3dev reconcile-game-update` to inspect the
exact supported build and dependency checks. It does not modify the executable.
After building the reviewed adapters, `--apply` performs a backed-up, checked
reconciliation; unknown builds remain blocked. See
[Steam update compatibility](docs/COMPATIBILITY.md) for qualification and
hash-guarded rollback. `install-native` is not an executable-update bypass.

## Dependencies and data

The current host has Steam/Proton, `xdotool`, Spectacle, KDE KWin and Python GI/DBus
support. The native protocol uses the existing loopback bridge. Research/UI tools
have their own environment under `research/python-env`; native build scripts use
the pinned compiler/SDK under `research/`. These local dependencies are retained
on this host and intentionally absent from a source clone. See
[native/README.md](native/README.md), [research/README.md](research/README.md)
and `research/findings.json` for build inputs and provenance.

Optional Rust evidence reader:

```sh
cargo build --locked --manifest-path readers/shadow-rust/Cargo.toml
```

`--offline` is supported when dependencies are already cached. Python verification
does not require Rust. Local config, receipts, sessions, backups, raw traces and
extracted/downloaded assets are ignored by Git. Worktrees share installation
state but retain their own source and build outputs. Worktrees share installation ownership; do not copy receipts or create a second runtime.

For Python consumers, add the canonical checkout to `sys.path` and import
`debugger.Client`. The existing `support.manage` helper name is retained for
compatibility, but now aliases this repository's `game_paths` module; it no longer
imports the combat lab's `manage.py` or any balance code.