docs: user-facing documentation and signing key

2026-08-27 12:32:26 +01:00
commit 017c04fc3c
16 changed files with 3422 additions and 0 deletions
@@ -0,0 +1,114 @@
+<!-- Generated from the Runi source repository at v0.4.0. -->
+<!-- Edit the original there, not this copy. -->
+
+# OptiScaler providers
+
+Runi exposes two explicit player-facing paths. **Runtime managed** is
+recommended when the selected runner passes the complete setup, redirection and
+configuration probe. **FSR 4.1.1 INT8** installs one pinned, validated nightly
+pipeline beside the game executable. They are mutually exclusive.
+
+## Providers and ownership
+
+### GE-Proton Integrated
+
+The integrated provider is available only when the selected runner implements
+the complete OptiScaler contract. Runi does not infer support from the
+runner name or version alone. It inspects the installed runner for setup,
+dispatcher, DLL-redirection and structured-configuration support.
+
+At launch Runi supplies the dedicated `PROTON_USE_OPTISCALER`,
+`PROTON_OPTISCALER_NAME` and, when needed, `PROTON_OPTISCALER_CONFIG` variables.
+`PROTON_FSR4_UPGRADE` enables the runner-managed FSR 4 path. GE-Proton owns the
+download cache and files placed in the Wine prefix; disabling or migrating the
+provider does not delete those runner-owned files.
+
+### FSR 4.1.1 INT8
+
+The quality-first path downloads official nightly `nightly-20260817`, verifies
+the complete archive plus the loader and FSR 4.1.1 upscaler hashes, installs a
+selected proxy DLL beside the game executable, and explicitly sets
+`Fsr4ForceModel=2`. The validation watermark is enabled by default for the
+first test and can be disabled in Advanced before installation. It owns only
+the files it installs and its corresponding `WINEDLLOVERRIDES` token, so removal
+restores previous files and prunes only empty directories it created.
+
+Generic stable manual injection remains available to the CLI and existing
+configurations for compatibility, but it is no longer a third GUI choice.
+
+The OptiScaler tab audits the pinned loader, nested FSR 4.1.1 DLL and required
+INT8 INI selection separately. A missing or changed component is reported as an
+incomplete installation rather than silently falling back.
+
+The integrated provider does not require player-supplied DLLs: the compatible
+runner owns provisioning. If the runtime probe fails, its card is unavailable
+and the pinned INT8 path remains explicit rather than being selected silently.
+
+## Selection and migration
+
+The stored provider preference and the provider already applied are separate:
+
+- **Runtime managed** requires a successful capability probe and is unavailable
+  otherwise.
+- **FSR 4.1.1 INT8** always uses the pinned, reversible game-directory provider.
+- Legacy Auto and generic Manual preferences remain readable for compatibility,
+  but new GUI configuration does not create them.
+
+Changing runners can change Auto's resolution. Runi blocks Play when the
+resolved provider no longer matches the applied provider; it never silently
+places or removes DLLs during launch. Use the migration action in the game tab
+or the CLI:
+
+```bash
+runi optiscaler status <game-id>
+runi optiscaler migrate <game-id> --to ge-integrated --fsr4
+runi optiscaler migrate <game-id> --to manual --version latest
+```
+
+Migration is explicit, transactional and receipt-backed. A manual recipe is
+removed through its normal rollback path before Integrated is configured, and
+its source, parameters and retained unrelated settings are recorded so the
+manual setup can be reconstructed if migration fails. Migration in the other
+direction disables the integrated launch path before installing the reversible
+manual provider.
+
+Raw integrated-provider variables in `[env]` are rejected because they bypass
+ownership and can activate both paths. Play is also blocked if manual tracking
+files coexist with an integrated selection.
+
+## FSR 4 behavior
+
+Runtime-managed FSR 4 is not an alias for the pinned FSR 4.1.1 INT8 path. The
+runner manifest chooses a compatible component set and may combine different
+component versions. The INT8 path is pinned to the exact tested nightly and
+checksums, so Runi does not claim that both methods are byte-for-byte or
+performance equivalent.
+
+For a detected DirectX 12 game, the integrated setup selects the DX12 FSR 3.1
+input path before requesting the FSR 4 upgrade. DirectX 11 and Vulkan use their
+corresponding DX12-interoperability input. The Vulkan-to-DX12 FSR 4 recipe path
+requires Proton 11 or newer.
+
+In games with a DLSS input, select DLSS in the game and use `Insert` to inspect
+the OptiScaler overlay. The overlay is the authoritative check for the
+intercepted input, selected output and loaded versions.
+
+## Status and troubleshooting
+
+The OptiScaler tab and `runi optiscaler status <game-id>` distinguish
+disabled, configured, ready, inconsistent and migration-required states.
+For the manual provider, JSON status also includes an `fsr411` audit with its
+own state and the missing or invalid components.
+`runi doctor` additionally reports stale manual tracking, duplicate raw
+provider variables and provider migrations required after runner changes.
+
+If a GUI process that was already open reports that schema v9 is unsupported,
+restart Runi so the running Python process loads the updated application
+code. Editable `pipx` installations already point at the checkout and do not
+need to be reinstalled for source changes.
+
+The integrated path was validated on a real GE-Proton11-5 installation. Kusan:
+City of Wolves confirmed provisioning, cached reuse, DLL redirection and the
+disabled control. Atomic Heart then confirmed the complete gameplay path after
+migration from the manual recipe: the overlay loaded, DLSS input was
+intercepted, FSR 4 output worked and gameplay remained stable.