runi-dist/docs/user-flows.md

<!-- Generated from the Runi source repository at v0.4.0. -->
<!-- Edit the original there, not this copy. -->

# User flows

See [config-schema.md](config-schema.md) for the exact fields referenced
below, and architecture.md (source repository) for how `run` resolves all of
this internally.

## 1. First run on a fresh machine

`runi versions` auto-discovers whatever's already installed (Steam's
official Proton if Steam is present; nothing else yet). To get GE-Proton:
`runi versions list-remote --source ge-proton` shows installable
releases, `runi versions install ge-proton latest` downloads, verifies
checksum, extracts into `compatibilitytools.d` with a progress bar, and now
shows up in `runi versions`.

## 2. Add and run a standalone `.exe` (no storefront)

```
runi add ~/Games/MyIndieGame/game.exe --name "My Indie Game"
runi run my-indie-game
```

Exe path validated, `game.id = my-indie-game` (unique slug),
`identity.umu_gameid = umu-default` (shared fallback, no game-specific fixes — expected for an
unknown title). `run` resolves backend=umu (the global default), builds
`PROTONPATH`/`WINEPREFIX`/`GAMEID=umu-default`, execs `umu-run`. First launch
creates the Wine prefix.

## 3. Add a second build of a game you already have

Keeping two builds installed at once — a working one and a newer one you want
to test — is a normal thing to do. Both derive the same id, so Runi
resolves it instead of overwriting:

```
runi add ~/Games/Mortal.Shell.II.v92120-P2P/.../MortalShell2-Win64-Shipping.exe \
  --name "Mortal Shell II"

added mortal-shell-ii-cl92120 (Mortal Shell II)
note: a different copy of 'Mortal Shell II' is already registered as
mortal-shell-ii; this one is registered alongside it (build version cl92120,
from pe-file-version)
shared with the other copy: game identity, notes, artwork
kept separate: Wine prefix, settings, environment, logs, save backups, mod receipts
```

The suffix is the build version read from the executable, so the id says which
copy it is. When the two copies report the same version — common for engines
that stamp their own version rather than the game's — there is nothing to tell
them apart and Runi asks instead of guessing:

```
Error: 'Ascend to ZERO' is already registered as ascend-to-zero and no build
version tells the two copies apart; re-run with --id <unique-id> to add it as a
separate installation
```

In the GUI this is one dialog with the proposed id pre-filled and editable,
showing the raw version string it came from.

**If you moved or renamed the folder instead**, that is not a second copy —
Runi recognises the installation by the marker inside it and offers to
repoint the existing registration, keeping its prefix, saves, settings and
mods:

```
Error: this installation is already registered as 'Mortal Shell II'
(mortal-shell-ii); it appears to have moved
```

## 4. Add a Steam game with a different Proton version than Steam's own choice

```
runi steam-scan
runi add --steam-appid 292030 --backend native --proton GE-Proton9-27
```

`steam-scan` lists installed titles with their AppIDs. `add --steam-appid`
resolves title/exe path automatically from the scan (no manual path-typing),
sets `game.id = steam-292030`, `identity.steam_appid = 292030`, and
`identity.umu_gameid = umu-292030` (so
protonfixes still key correctly even though this game runs outside Steam's
own launch path). `runi versions` would have already flagged
`GE-Proton9-27` as safe for `native` (no `⚠ needs steamrt`), so `add` doesn't
need to warn here.

In the GUI, Runtime separates **Launch Engine** from **Runner family** and
**Version**. UMU Automatic selects the newest installed GE-Proton; Direct
Proton selects an explicit installed build.

Manual game creation asks for the executable and suggests Display Name from a
local Steam manifest, PE ProductName/FileDescription, a cleaned installation
folder or finally the executable filename. The player may edit the suggestion.
Runi then resolves Steam/UMU identity in the background from a
game-provided `steam_appid.txt`, corroborated AppID metadata in bounded local
INI files, an exact local Steam manifest match, or an exact Steam Store title
match. Local AppIDs are validated directly through Steam app details, so an
imperfect folder title does not prevent identification. Ambiguous matches
require confirmation; unavailable or failed validation leaves `umu-default`. Runtime shows the
canonical title, source, confidence and validation timestamp, retains editable
technical fields and offers explicit revalidation.
Settings → Runners manages GE-Proton, UMU-Proton, Proton-CachyOS and experimental
Proton-EM releases. Proton Experimental is detected but remains Steam-managed.
Installed versions show manager and usage badges. Selecting a games badge
expands the titles configured to use that exact version; removal remains
disabled until those games are moved to another Runtime version.
Selecting an already installed release changes the action to **Installed**.
New builds are installed transactionally, so Runi never extracts over an
existing runner or exposes a partially extracted build to Steam/UMU.

### Add from Dolphin

On KDE Plasma, enable **Settings → Desktop Integration → Show “Add to
Runi” in Dolphin**. Right-click one local Windows `.exe` and choose
**Add to Runi**. Dolphin sends the path to the already-running GUI, or
starts it when necessary, and the normal Add Game review opens.

The local candidate check is shared by Dolphin, the GUI and `runi add`.
Malformed files and DLLs are blocked. A valid PE whose role is unclear, or a
file that resembles a settings/installer utility, is shown with evidence and
ranked alternatives but may still be added deliberately. Selecting a game
already in the library focuses its existing card instead of creating a
duplicate. Requests received while a game or modal task is active remain in a
small in-memory queue.

The same entry point is available for desktop integration testing:

```bash
runi gui --add-file /path/to/game.exe
runi desktop-integration dolphin status
runi desktop-integration dolphin install
runi desktop-integration dolphin remove
```

## 5. Add a GOG/Epic title

```
runi add ~/Games/SomeGogGame/game.exe --store gog --name "Some Game"
```

Manual registration in v1 (no Heroic/Legendary auto-scan yet — see
roadmap.md (source repository)); `STORE=gog` is still forwarded so protonfixes keyed
by store apply if the umu-database has an entry for it.

## 6. Add games from Ubisoft Connect

In the GUI choose **+ → Ubisoft Connect**. Install the client automatically or
import an existing Ubisoft prefix, open it to log in/install games, then close
it. Review the locally detected titles and import the selected ones. Later,
**Play** sends the Ubisoft deeplink directly; **Tools → Stores** reopens client
management. See [ubisoft-connect.md](ubisoft-connect.md) for the shared-prefix,
runner, process-monitoring and cloud-sync rules.

## 7. Tweak display settings on a stuttery game

```
runi config steam-292030 \
  --set gamescope.enabled=true \
  --set gamescope.output_width=2560 --set gamescope.output_height=1440 \
  --set gamescope.render_width=1920 --set gamescope.render_height=1080 \
  --set gamescope.filter=fsr \
  --set mangohud.enabled=true

runi run steam-292030 --dry-run
```

`--dry-run` prints the fully composed command so you can verify before
committing:

```
gamescope -W 2560 -H 1440 -w 1920 -h 1080 -F fsr --mangoapp -- umu-run witcher3.exe
```

Note MangoHud folded into gamescope's own `--mangoapp` flag rather than
becoming a separate wrapper stage (gamescope's nested compositor doesn't
support the plain MangoHud overlay). Drop `--dry-run` to launch for real.

## 8. Install OptiScaler for a game with a weak native upscaler

```
runi optiscaler install steam-292030 --dll dxgi.dll
runi run steam-292030
```

Downloads the release, backs up any `dxgi.dll` the game already shipped,
copies OptiScaler's files alongside the game exe, sets
`env.WINEDLLOVERRIDES = "dxgi=n,b"` and `[optiscaler]` state in the config.
`run` launches normally; in-game `Insert` opens the OptiScaler overlay to pick
an upscaler backend.

```
runi optiscaler remove steam-292030
```

Restores the original file from the recorded manifest and clears the env
override.

## 9. Manage Proton versions over time

```
runi versions install ge-proton latest
runi versions remove GE-Proton9-20
```

The second command fails with `VersionInUseError` listing which games still
reference that version; re-point those games first
(`runi config <id> --set runtime.proton=GE-Proton9-27`), then removal
succeeds.

## 10. Clean up

```
runi remove my-indie-game
```

The CLI deletes the registration and its Wine prefix by default; pass
`--keep-prefix` to preserve the prefix. In the GUI, removing only the
registration is the safe default. A separate checkbox can permanently delete
the marked game installation and its prefix, and warns that local saves and
settings stored in either location are also deleted. Runi refuses this
disk deletion when the installation ownership marker does not match. The
originally selected folder remains the deletion unit even when the executable
is nested deeply; recognized Unreal packages include the sibling `Engine`
directory rather than only `Binaries/Win64`. Existing Runi save backups
are kept.

For Ubisoft games, the shared prefix is always preserved. The GUI can open
Ubisoft Connect's own uninstall confirmation before removing the Runi
registration; it never deletes the Ubisoft game directory itself.

## 11. Recipes, and what replaced them

**There is no Recipe tab, and adding a game no longer offers one.** Recipes
asked the player to assemble a setup from required items, recommended items,
supplied asset files and a review step - which is a great deal of deciding for
someone who wanted to press Play. The OptiScaler tab now narrows the same
ground to two explicit choices with automatic selection between them, so the
flow that used to live here is [flow 8](#8-install-optiscaler-for-a-game-with-a-weak-native-upscaler).

What remains is rollback. A game that had a recipe applied *before* the
retirement still carries its receipt, and shows a **Recipe (Legacy)** entry
for as long as that receipt exists, so the transaction can still be reverted.
Nothing creates a new one.

For an upscaler build with no official source to automate - a leaked FSR
package, a DLSS/XeSS swap - the supported path is a customize profile, which
is [flow 13](#13-apply-a-community-upscaler-workaround-manually-advanced).

## 12. Known launch compatibility

When Runi recognises an exact canonical game with a verified launch
workaround, it applies the safe default during registration or before launch
and shows a short notification. Explicit user launch options take precedence.

The first verified case is Pathogenic's Windows build on Linux: its Godot 4.7
D3D12 path crashed in RADV while creating a VKD3D compute pipeline, while the
same executable ran correctly with `--rendering-driver vulkan`. This argument
is scoped to Pathogenic's PGID; it is not inferred for other Godot games.

## 13. Apply a community upscaler workaround manually (advanced)

Real example, validated end-to-end: enabling a leaked FSR 4.1.1 INT8 build
on non-RDNA4 hardware, for a game with OptiScaler already installed.

```
runi optiscaler install my-game --dll dxgi.dll
```

Write `~/.config/runi/profiles/fsr411-workaround.toml` once (see
[customize-profiles.md](customize-profiles.md) for the full format):

```toml
[profile]
name = "fsr411-workaround"
description = "Community FSR 4.1.1 INT8 workaround for non-RDNA4 GPUs"

[[files]]
src = "/home/user/Downloads/FidelityFX-Samples-v2.3.0-prebuilt/.../amd_fidelityfx_upscaler_dx12.dll"
dest = "amd_fidelityfx_upscaler_dx12.dll"

[[ini_edits]]
file = "OptiScaler.ini"
[ini_edits.set]
Fsr4Update = "true"
```

```
runi customize apply my-game fsr411-workaround
runi run my-game
```

In-game, press `Insert` for the OptiScaler overlay and select FSR4 → the
INT8 model. If a newer leaked build shows up later, just edit the profile's
`[[files]]` source paths and re-`apply` — the previous version is reverted
automatically before the new one is applied.

```
runi customize remove my-game
```

Restores the pre-customize state exactly (the stock OptiScaler files,
`Fsr4Update` back to its original value) — OptiScaler itself stays installed.

## 14. Enable LinUwUx for a Reflex/DenuvOwO-protected game

```
runi config my-game --set linuwux.enabled=true
runi run my-game --dry-run
```

`--dry-run` confirms the wrapper is in place:

```
linuwux umu-run MyGame.exe
```

Drop `--dry-run` to launch for real. If the Technology Scan (GUI Overview
tab, or `runi doctor`) already flagged a "Compat Shim: LinUwUx (Reflex)"
or "LinUwUx (DenuvOwO)" finding for this game, that's an informational hint
only — Runi never enables the wrapper automatically.

`[linuwux].debug=true` adds `LINUWUX_DEBUG=1` for troubleshooting; leave it
off for normal play, since it produces heavy `sigsys redirect` logging.

`[linuwux].enabled` cannot be combined with `[gamescope].enabled` —
confirmed crashing on real hardware (the gamescope session dies before the
game process ever starts), not just untested. `runi run`/`--dry-run`
refuse with `IncompatibleWrapperError` up front rather than launching into a
crash; disable gamescope first if you need linuwux.

`[mangohud].enabled` works fine alongside linuwux — Runi activates it
with `MANGOHUD=1` alone instead of mangohud's usual `LD_PRELOAD` wrapper
(which does collide), confirmed working on real hardware. No extra
configuration needed; just enable both.

If you want a custom MangoHud layout via `[mangohud].config_file`, MangoHud's
own `core_load` option (per-core CPU load/frequency) is worth knowing about:
bisected on real hardware (Monster Hunter Wilds) that enabling `core_load`
forces MangoHud back to a vertical layout even with `horizontal` set - a
per-core breakdown doesn't fit a horizontal row. Every other stat option
(`cpu_stats`, `gpu_stats`, `ram`, `vram`, `frame_timing`, etc.) composes fine
with `horizontal`; only `core_load` is the exception. This is MangoHud's own
behavior, unrelated to Runi or linuwux specifically.

That exact layout ships as a bundled preset - see flow 15 below - so you
don't have to rebuild it by hand:
`runi mangohud-preset apply horizontal-complete <id>`.

LinUwUx upstream documents only GE-Proton and Proton-CachyOS as supported
(official Valve Proton is not). If `[runtime].proton` resolves to anything
else, `runi doctor` surfaces a non-blocking advisory finding rather
than refusing to launch:

```
runi doctor
```

Requires `linuwux` to already be on `PATH` (installed via upstream's own
`install.sh`/`build.sh --install` — see
[github.com/brcly/linuwux-runtime](https://github.com/brcly/linuwux-runtime));
Runi never installs or manages it.

## 15. Save and apply a named MangoHud preset

```
runi mangohud-preset list
```

Shows every available preset — bundled (shipped with Runi) plus any
you've saved locally. Runi ships one bundled preset out of the box,
`horizontal-complete`, the exact layout validated in flow 14 above:

```
runi mangohud-preset apply horizontal-complete my-game
runi config my-game --set mangohud.enabled=true
```

This writes the preset's content to a per-game file
(`~/.local/share/runi/mangohud/<id>.conf`) and sets
`[mangohud].config_file` to it — the same effect as building the file by
hand and pointing `config_file` at it, just one command. `runi run
my-game --dry-run` shows the resolved `MANGOHUD_CONFIGFILE` to confirm.

To save your own config (built by hand, or already applied to a game you're
happy with) as a reusable preset:

```
runi mangohud-preset save my-layout --from-game my-game --description "my favorite layout"
# or, from an arbitrary file:
runi mangohud-preset save my-layout --from-file ~/some/MangoHud.conf
```

Saved presets are plain TOML at
`~/.config/runi/mangohud-presets/<name>.toml`; a local preset with the
same name as a bundled one takes priority, so you can override
`horizontal-complete` itself by saving your own version under that name.

```
runi mangohud-preset remove my-game
```

Clears `[mangohud].config_file` (falling back to MangoHud's own default
resolution order) and deletes the applied per-game file.

**Deliberately per-game only** — there is no "apply globally" (writing
`~/.config/MangoHud/MangoHud.conf`). That file is commonly managed by
third-party tools like GOverlay/MangoJuice; a second tool silently writing
over it (even with a backup taken first) creates an ongoing "who owns this
file" conflict with no clean resolution, confirmed real on a machine already
running MangoJuice. If you want a preset's layout system-wide, apply it to
each game you care about, or use GOverlay/MangoJuice's own global-config
tooling directly.

## 16. Import a Ludusavi save backup into a game's prefix

CLI-only, low-key utility — reads a [Ludusavi](https://github.com/mtkennerly/ludusavi)
backup folder (`mapping.yaml` + `drive-C/`, the "simple" non-zip format)
directly and copies the files into the game's own Wine prefix. No
dependency on the `ludusavi` binary itself.

```
runi saves import-ludusavi my-game /path/to/ludusavi/backups/My\ Game --preview
```

`--preview` shows exactly what would be copied — source → destination →
size — without writing anything. The prefix must already exist (launch the
game for real at least once first); otherwise this refuses rather than
half-creating one.

```
runi saves import-ludusavi my-game /path/to/ludusavi/backups/My\ Game
```

Copies every recorded file, verifying each one's SHA1 against what
`mapping.yaml` recorded (catches SMB/network corruption, not just logic
bugs), and — unless `--no-set-save-path` is passed — updates
`[saves].path` to the backup's own save location, so Runi's own
`saves backup`/`restore` also point at the right place afterward. If the
computed destination already has files in it, the *current* state is
backed up first via the normal `saves backup` mechanism, so an import is
always reversible.

Two real things this surfaced, worth knowing if a result looks surprising:

- **Path casing and shared folders.** Ludusavi records the source Windows
  machine's own path casing (`Users`, capitalized) and username segment
  (e.g. `Users/cvarandas/...`). Wine's real prefix directory is lowercase
  (`users`) with its own account name (`steamuser` in every
  runi-managed prefix) — a blind copy would create a bogus sibling
  directory the game never sees. The importer resolves both against what's
  actually on disk. It also knows `Users/Public/...` is a real, shared
  folder, not a personal account to remap — confirmed by a real game (The
  Sinking City 2) whose save data legitimately lives partly under `Public`.
- **A RUNE/crack config's declared save path and a Ludusavi backup's
  actual files can legitimately disagree.** The Sinking City 2's RUNE
  crack (`steam_emu.ini`) declares saves at
  `users/Public/Documents/Steam/RUNE/2825860` — that's likely where RUNE
  stores its *own* Steam-emulation state (fake achievements/cloud markers),
  not necessarily the engine's native save files, which for this game
  turned out to be `AppData/Local/TSC2/Saved` (confirmed by both the real
  backup content and an actual game launch). The importer prints a note
  when this happens (reusing Runi's existing RUNE detection as a
  cross-check) but always imports to where the backup's files really are.

**Runi cannot verify a backup matches the installed game's specific
version/release** — Ludusavi's `mapping.yaml` records hashes for the save
data itself, not the source machine's game build. The safety backup above
is the actual mitigation; confirm compatibility the same way it was
confirmed here — launch the game and check.

Only the simple (non-zip) backup format is supported; a zip-format backup
folder is refused with a clear error rather than silently mishandled.