runi-dist/docs/features.md

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

# Canonical feature catalogue

This document is the canonical inventory of Runi's implemented product
capabilities. It answers **what Runi can do today**; it is not a roadmap,
a configuration-field reference or an implementation history.

- **GUI** means the capability is available from `runi gui`.
- **CLI** means it has a public command-line entry point.
- **Automatic** means the core applies it as part of registration, inspection
  or launch rather than exposing a separate control.

Exact per-game and global configuration fields remain authoritative in
[the configuration schema](config-schema.md). Planned, deferred and rejected
ideas belong in the roadmap (source repository), not in this catalogue.

## Library and application experience

| Capability | Surface | Current behavior |
|---|---|---|
| Launcher-first game library | GUI | Grid and list views, title search, store/collection filters, feature badges, readiness state and running-state controls. |
| Per-game cockpit | GUI | Overview, Runtime, HDR, Controller, OptiScaler, Lossless Scaling, Logs, Notes and Saves tabs. Windows-only tools are hidden where they do not apply; an applied legacy recipe temporarily exposes a rollback-only Recipe tab. |
| Game collections and classification | GUI, CLI | Distinguishes PC games, Windows ports and Linux-port classification while preserving the original platform. Custom original-platform labels are supported. Linux ports are classification-only in the current release. |
| Controller navigation | GUI | A supported Steam Controller can navigate the library, dialogs and game tabs. Launcher input is locked while a game session owns the controller. |
| Appearance and placement | GUI | System, light, dark and Breeze theme choices; optional primary-monitor placement where the desktop environment supports it. |
| Responsive long-running work | GUI | Runner installation, cover refresh, OptiScaler installation, save backup and other long operations run outside the UI thread. |
| Single-instance local intents | GUI, Automatic | A bounded user-local channel can focus the existing window and queue an add-game request, including requests from Dolphin. It is not a daemon or general remote-control API. |

## Game registration, discovery and identity

| Capability | Surface | Current behavior |
|---|---|---|
| Standalone Windows game registration | GUI, CLI | Registers a selected PE executable with name, store, launch arguments, backend and runner choices. Invalid targets and DLLs are rejected; ambiguous utilities produce reviewable warnings and nearby executable alternatives. |
| Steam library scan and import | GUI, CLI | Reads installed Steam libraries and imports a selected AppID without modifying Steam's compatibility-tool selection. Runtime/tool AppManifests can still appear in scan results. |
| GOG and Epic registration | GUI, CLI | Installed executables can be registered manually and labelled as GOG or Epic. Automatic Heroic/Legendary discovery is not implemented. |
| Ubisoft Connect shared store | GUI | Installs or imports Ubisoft Connect in one managed shared prefix, opens it for sign-in/installation, scans local Ubisoft records, imports reviewed games and launches them by deeplink. Runner changes apply to the shared installation, and process monitoring covers the real game lifecycle and optional cloud-sync wait. |
| Dolphin integration | GUI, CLI | Optional, user-scoped **Add to Runi** service-menu action for Windows executables. Installation, status and removal are available in Preferences and under `desktop-integration dolphin`. |
| Launch-target detection | GUI, CLI, Automatic | Detects the primary executable, install root, useful auxiliary actions and known launch-provider shapes during registration. Supported providers are executable, Xenia, RPCS3 and Ubisoft; commands can run through Proton or directly on the host as appropriate. |
| Multiple launch actions | GUI, CLI | A registration can expose Play plus configuration, emulator or tool actions with their own executable, arguments, working directory and wrapper policy. CLI selection uses `run --action`. |
| Canonical game identity | GUI, Automatic | Separates the local registration ID, canonical Runi Game ID and installation UUID. Identity evidence can include Steam, UMU, Ubisoft and SteamGridDB identifiers and records confidence/source. |
| Reinstall recognition | GUI, CLI, Automatic | Install markers and archived retired configuration allow compatible state to be reconnected after a reinstall, or deliberately replaced with a fresh installation identity. |
| Parallel installations | GUI, CLI | Two copies of the same game register side by side. A colliding registration is offered an id suffixed with the build version read from the executable, never a numeric counter, and asks for a discriminator when no build version tells the copies apart. Both share identity, notes and artwork; prefix, settings, logs, save backups and mod receipts stay separate. |
| Moved-installation recognition | GUI, CLI | A game folder that was moved or renamed is identified by its install marker and repointed, keeping its prefix, saves, settings and mod receipts, instead of being registered a second time. |
| Curated compatibility defaults | Automatic | Exact canonical games can receive narrowly scoped, safe launch defaults from the bundled compatibility catalogue. Explicit user launch options take precedence. |

See [game identity](game-identity.md), [launch providers](launch-providers.md),
[Ubisoft Connect](ubisoft-connect.md) and [user flows](user-flows.md).

## Runners, prefixes and launch composition

| Capability | Surface | Current behavior |
|---|---|---|
| UMU backend | GUI, CLI | Wraps `umu-run`, supplies the UMU Game ID and uses its Steam Runtime handling. |
| Native Proton backend | GUI, CLI | Drives a compatible installed Proton build directly without routing the launch through Steam. Builds that declare a required Steam Runtime are excluded from native use. |
| Per-game runner selection | GUI, CLI | Stores an explicit Proton build or automatically chooses an installed GE-Proton build. |
| Runner discovery | GUI, CLI | Discovers Steam official Proton, GE-Proton, UMU Proton, Proton-CachyOS, Proton-EM and custom local builds. |
| Runner catalogue and lifecycle | GUI, CLI | Lists installed and remote builds, installs supported release sources, and removes unused builds. Removal is refused while a registered game references the build. |
| Managed or custom Wine prefixes | GUI, CLI | Uses an XDG-managed per-game prefix by default or a user-selected prefix override. Prefix folders can be opened directly. |
| Per-game launch environment | GUI, CLI | Persists executable arguments, working directory, arbitrary environment variables, UMU identity, CPU affinity and runner/backend selection in plain TOML. |
| Safe command composition | GUI, CLI, Automatic | Produces an argument vector without shell interpolation and composes runtime, graphics, environment and action layers in a deterministic order. |
| Dry-run preview | GUI, CLI | Shows the exact environment and command without launching the game. CLI output can be human-readable or JSON. |
| Launch lifecycle | GUI, CLI | GUI launches are detached and observable so Play/Stop and running-state locking remain responsive; CLI launches return the process exit status. |
| Debug and logging controls | GUI, CLI | Normal, verbose and Proton-debug launch modes; console or per-installation file output; a stable `latest.log`; and an in-app Logs viewer. CLI flags can override saved logging for one launch. |
| LinUwUx compatibility wrapper | GUI, CLI | Optional `linuwux` LD_PRELOAD wrapper prefix for Reflex/DenuvOwO-style anti-cheat/DRM loaders under Proton/UMU. Runi only toggles presence and an optional debug flag; linuwux's own fingerprinting, variant resolution and WINEDLLOVERRIDES merging are untouched. `runi doctor` flags a non-blocking advisory if the selected Proton build is not GE-Proton/Proton-CachyOS, the only builds linuwux upstream documents as supported. Combining it with gamescope is refused outright (`IncompatibleWrapperError`) — confirmed crashing on real hardware. MangoHud works alongside it via `MANGOHUD=1` instead of MangoHud's own `LD_PRELOAD` wrapper, which does collide. |
| MangoHud presets | GUI, CLI | Named, reusable MangoHud overlay configs saved by Runi (`~/.config/runi/mangohud-presets/`) and applied to a chosen game's `[mangohud].config_file` in one command. Ships one bundled preset (`horizontal-complete`). Deliberately per-game only — never writes the global `~/.config/MangoHud/MangoHud.conf`, which third-party tools like GOverlay/MangoJuice commonly manage themselves. |

See architecture (source repository), [launch providers](launch-providers.md)
and [the configuration schema](config-schema.md).

## Display, performance and scaling

| Capability | Surface | Current behavior |
|---|---|---|
| Gamescope | GUI, CLI | Per-game output/render resolution, FSR/NIS/linear/nearest filter, scaler mode, fullscreen/borderless mode, refresh rate and frame-rate cap. The GUI groups each resolution into an editable preset selector, pairs rate preset sliders with custom numeric input, and initializes new games from the primary monitor when available. |
| MangoHud | GUI, CLI | Per-game overlay, frame-rate limit and optional configuration file. The GUI provides a prominent header toggle, an editable preset slider for the limit and an Advanced area for the configuration path. When Gamescope is active, Runi composes MangoHud through Gamescope's supported `--mangoapp` path. |
| Proton fullscreen FSR | GUI, CLI | Enables Proton's built-in fullscreen FSR hack and strength independently of Gamescope. |
| CPU affinity | GUI, CLI | Applies a Linux CPU-list restriction to the complete launch chain through `taskset`. |
| Native HDR | GUI, CLI, Automatic | Enables native game HDR through an already-configured Gamescope session, verifies the matching WSI layer, Vulkan capability and KDE output state where available, and selects a runner-supported Proton/DXVK flag. Confirmed failures block launch; an unverifiable desktop produces an explicit warning. Runi never changes desktop or monitor HDR/WCG settings. |
| HDR display and OS guidance | GUI, Automatic | Reads KDE output calibration metadata and presents peak luminance, reference white, colour profile, gamut, RGB range and bit depth as read-only calibration guidance. |
| Community HDR settings research | GUI | Optional, disabled-by-default OpenAI research initiated only by the player. It performs at most three searches across an audited source allowlist and can add one author-restricted HDR Game Analysis guide with at most four public images. It returns cited structured slider values, exposes conflicts and never applies settings automatically. |
| Persistent HDR knowledge | GUI, Automatic | Stores the latest three successful research runs per canonical game in SQLite, shares them across registrations and keeps stale results visible after 30 days. Failed refreshes do not replace successful evidence. |
| OptiScaler provider management | GUI, CLI, Automatic | The GUI offers two mutually-exclusive paths: capability-probed Runtime managed support and a pinned, checksum-verified FSR 4.1.1 INT8 quality-first installation. The INT8 path retains reversible game-file backups and owned Wine overrides; runtime setups use runner variables and prefix tracking without placing proxy DLLs beside the game. Provider changes require an explicit, receipt-backed migration. Generic manual installation remains available through the CLI for compatibility. |
| Lossless Scaling frame generation | GUI, CLI configuration | Detects a supported `lsfg-vk` Vulkan layer and the user's Steam-owned Lossless Scaling installation, then enables per-game LSFG frame generation with multiplier, flow scale, performance mode and supported version-specific options. It does not modify the global lsfg-vk profile. |
| Feature compatibility guidance | GUI | Reports missing scaling dependencies and relevant Gamescope, HDR, Vulkan and anti-cheat cautions. OptiScaler upscaling and LSFG frame generation can be composed, but enabling frame generation in both technologies is unsupported. |

Lossless Scaling on Windows includes upscaling, but Runi's Linux
integration currently configures only LSFG frame generation through lsfg-vk.
See [Lossless Scaling](lossless-scaling.md) and the display pipeline in
architecture (source repository).
OptiScaler provider selection, migration and runner ownership are documented in
[OptiScaler providers](optiscaler.md).

## Controllers and Steam Input

| Capability | Surface | Current behavior |
|---|---|---|
| Steam Controller detection | GUI, Automatic | Detects supported 2026 Steam Controller USB and wireless-puck transports at startup and on hotplug through SDL3, with a legacy evdev fallback. Other physical controller families are not supported. |
| Runi Direct Xbox mode | GUI | Maps the physical controller through SDL3 to a virtual Xbox 360-shaped `uinput` device for Wine/XInput games, without requiring Steam. Desktop mouse/keyboard event nodes are temporarily grabbed during the session to prevent duplicate input. |
| Runi Direct Keyboard & Mouse mode | GUI | Per-game mapping for games without native controller support, including pointer tuning, keyboard/mouse bindings, rear buttons and right-trackpad mouse input. Gyro, rumble and mode layers are not implemented. |
| Curated and user controller profiles | GUI | Bundled profiles can be overridden per canonical game and reset without changing the bundled definition. Profiles survive registration removal and re-import. |
| Steam Input launch mode | GUI, Automatic | Creates and maintains a deterministic Runi-owned non-Steam shortcut, including stable AppID, launch options, tags and artwork. Steam must be closed while the shortcut is created, repaired or removed. |
| Steam API provider inspection | GUI, Automatic | Detects supported Goldberg-derived, RUNE-style and unknown local Steam API provider capabilities. It can recommend Direct or Steam Input and apply only a narrowly supported, backed-up compatibility setting; it never replaces Steam API DLLs. |
| Controller diagnostics | GUI | Runs explicit SDL/uinput/Wine HID and XInput tracing, correlates runtime logs and stores a per-installation stage report. Normal launches do not enable the diagnostic trace. |

See [controller support](controller-support.md) for hardware requirements,
validated paths and current limits.

## Technology analysis and legacy recipes

| Capability | Surface | Current behavior |
|---|---|---|
| Bounded local Technology Scan | GUI, Automatic | Inventories graphics APIs, upscalers/frame generation, engines, middleware, anti-cheat, DRM and Steam Input evidence without treating a filename match as certainty. Upscaler versions are read from the binary's PE version resource, because one filename covers several versions. |
| PCGamingWiki enrichment | GUI | Adds sourced compatibility evidence in the background. SteamDB remains an explicit external link because it has no supported public API. |
| Runtime technology diagnostic | GUI | An explicit diagnostic launch can observe loaded runtime modules. It is never run silently. |
| Evidence and confidence model | GUI, Automatic | Retains source, observation time and confidence for findings and ties installation-specific evidence to the installation identity. |
| Legacy recipe preservation | GUI, Automatic | New games do not expose recipe discovery or application. When an existing installation has an applied receipt, Runi temporarily exposes **Recipe (Legacy)** so its exact rollback remains available. |
| Recipe engine and asset cache | Automatic | Existing declarative definitions, checksum-validated private assets and transactional receipts remain readable for compatibility and rollback. No remote catalogue or new GUI application flow is exposed. |
| Advanced Customize profiles | CLI | Applies named file-copy and INI-edit workaround profiles, records the previous state and restores it precisely. This remains the advanced/manual path for community modifications. |

See [Technology Scan](technology-scan.md), the retained recipe
subsystem (source repository) and [Customize profiles](customize-profiles.md).

## Artwork, metadata and preferences

| Capability | Surface | Current behavior |
|---|---|---|
| Steam artwork fallback | GUI, Automatic | Uses exact Steam identity to retrieve portrait library artwork from Steam's CDN. |
| SteamGridDB artwork | GUI | Supports API-key testing, exact candidate review, manual cover selection and optional automatic downloads for missing covers. |
| Ubisoft artwork | GUI, Automatic | Uses confirmed Ubisoft Store product identity to resolve official box art. |
| Custom covers and cache controls | GUI | Keeps user-selected covers separate from automatically downloaded cache; can refresh missing covers or clear only automatic artwork. |
| Cover and appearance preferences | GUI | Persists artwork settings, theme and window-placement behavior globally rather than per game. |

## Saves, notes, portability and recovery

| Capability | Surface | Current behavior |
|---|---|---|
| Save-path discovery and confirmation | GUI | Queries PCGamingWiki for candidate save locations, resolves Windows paths inside the prefix and lets the user confirm or enter a path manually. |
| Save backup and restore | GUI, CLI | Creates timestamped per-installation backups, lists them and restores a selected backup for a configured save path. |
| Persistent game notes | GUI, CLI | Stores Markdown findings outside the registration TOML. A canonical/shared notes key can preserve or relate notes across registrations. |
| Retired installation archive | Automatic | Removing a game archives its last configuration by installation identity so compatible state can later be reconnected. |
| Portable prefix bundles | CLI | Exports `.pfy` bundles containing the Wine prefix and selected Runi state, inspects metadata without extraction, verifies format and SHA-256 payloads, and imports transactionally without overwriting existing registrations or prefixes. Replacement and GUI bundle workflows are not implemented. |
| Registry/filesystem Doctor | GUI, CLI | Detects missing executables, install-marker mismatches, stale OptiScaler/Customize state and orphaned prefix/log/save-backup directories. Safe findings can be fixed; orphan deletion is a separate exact-path operation with confirmation. |
| Safe game removal | GUI, CLI | Unregisters a game and archives its configuration. The GUI keeps game files and the Wine prefix by default; its disk-deletion option removes both only after verifying the installation ownership marker and warns about local saves. Ubisoft games instead open the store client's confirmed uninstall flow without deleting the shared prefix. The CLI can preserve a normal game's prefix with `--keep-prefix`. |

See [portable prefix bundles](prefix-bundles.md), [game identity](game-identity.md)
and the Doctor behavior recorded in the implementation snapshot (source repository).

## Configuration, automation and safety

| Capability | Surface | Current behavior |
|---|---|---|
| Plain TOML configuration | GUI, CLI | One versioned file per game plus a small global configuration; files are human-editable and use standard XDG locations. |
| Schema-driven Runtime editor | GUI | Builds controls from the same model metadata used by the CLI schema, reducing drift between UI and stored configuration. |
| Self-describing schema | CLI | `runi schema` reports every configurable field, type, default, choices and description, with section filtering. |
| Configuration editing | CLI | Reads full game configuration, applies dotted `section.key=value` updates or opens the file in `$EDITOR`. |
| JSON automation output | CLI | State and query commands that expose structured results support `--json`; dry-run JSON contains the final environment and argument vector. Interactive launch, editor, desktop-integration and GUI entry points remain text-only. |
| Versioned migrations and backups | Automatic | Migrates older configuration schemas on load/save and preserves the previous file before the first write in a newer schema. |
| Atomic and ownership-aware writes | Automatic | Managed configuration, Steam shortcut, integration and state writes use bounded ownership markers, backups or atomic publication as appropriate. |
| Game-file rollback boundary | Automatic | OptiScaler, Customize and recipes record owned changes and preserve pre-existing files instead of treating a game directory as disposable. |

## Complete public CLI surface

This table is an index, not a replacement for `runi <command> --help`.
The hidden `steam-launch` implementation command is intentionally excluded
because it is owned by managed Steam shortcuts rather than being a user-facing
workflow.

| Command family | Operations |
|---|---|
| `add` | Register a standalone, Steam or classified Windows-port installation; reconnect archived state or start fresh. |
| `list` | List registered games. |
| `run` | Launch Play or an auxiliary action; preview, change verbosity and override logging for one run. |
| `config` | Read or edit per-game TOML and set individual schema fields. |
| `schema` | Inspect the configurable model. |
| `steam-scan` | Scan installed Steam AppManifests. |
| `versions` | List installed builds. |
| `versions list-remote` | List releases available from a supported source. |
| `versions install` / `versions remove` | Manage runner builds with in-use protection. |
| `optiscaler install` / `configure` / `status` / `migrate` / `remove` | Manage, inspect and migrate reversible per-game OptiScaler providers. `install` remains the explicit manual compatibility command. |
| `hdr status` | Inspect native HDR prerequisites, output state and warnings for one game. |
| `customize list` / `customize apply` / `customize remove` | Manage advanced community workaround profiles. |
| `bundle export` / `bundle inspect` / `bundle verify` / `bundle import` | Manage portable prefix bundles. |
| `desktop-integration dolphin status\|install\|remove` | Manage the Dolphin service-menu action. |
| `prefix open` | Open a game's Wine prefix. |
| `saves backup` / `saves list` / `saves restore` | Manage save backups. |
| `notes` | View or edit persistent game notes. |
| `doctor` / `doctor remove-orphan` | Audit managed state, apply safe fixes and explicitly remove one reported orphan. |
| `remove` | Unregister a game with prefix-retention control. |
| `gui` | Start the optional PySide6 application. |

## Optional dependencies and service boundaries

| Dependency or service | Required for |
|---|---|
| `umu-run` | UMU launch backend. |
| An installed Proton build | Native backend and explicit per-game runner selection. |
| PySide6 | GUI only; the base CLI remains usable without it. |
| Steam | Steam scan, Steam-owned Proton discovery and optional Steam Input launch mode. |
| Gamescope | Gamescope display pipeline. |
| Wayland HDR session, Gamescope WSI layer and HDR-capable Vulkan stack | Per-game native HDR. KDE output state is verified when `kscreen-doctor` is available. |
| MangoHud | MangoHud overlay when used without Gamescope; Gamescope must itself support `--mangoapp` for the combined path. |
| OptiScaler release access | OptiScaler installation; game ownership and compatibility remain the user's responsibility. |
| `lsfg-vk` plus Lossless Scaling from Steam | Per-game Lossless Scaling frame generation. |
| SDL3, `libevdev` and `/dev/uinput` access | Runi Direct Steam Controller input. |
| SteamGridDB API | Community artwork search and automatic non-Steam cover downloads; exact Steam CDN artwork does not require a key. |
| PCGamingWiki access | Online technology enrichment and save-location candidates; local scans and manual save paths continue to work offline. |

## Explicitly not implemented

The following commonly confused items are not current capabilities:

- automatic GOG, Epic, Heroic or Legendary library discovery;
- writing Steam's own per-game `CompatToolMapping` selection;
- live shortcut creation through Steam's undocumented `addnonsteamgame` URL;
- general support for physical controllers other than the Steam Controller;
- Lossless Scaling upscaling on Linux (the integration is LSFG only);
- a GUI for prefix bundle export/import or bundle replacement;
- whole-application state backup and restore;
- Runi Help, an OpenAI diagnostic agent or a shared online compatibility
  catalogue;
- a daemon or broad remote-control API;
- native Linux-port execution beyond the current classification model.

See the roadmap (source repository) for the status and rationale of future work.

## Maintenance rule

Every change that adds, removes or materially changes a product capability must
update this catalogue in the same commit. It must also update `CHANGELOG.md` and
the relevant specialist documentation when user behavior, requirements,
persistence, compatibility or rollback semantics change.

Roadmap proposals must not be listed as implemented. Conversely, once a feature
is shipped, its roadmap entry should link here or be moved into an implementation
history section so the two sources cannot contradict each other.