docs: user-facing documentation and signing key

docs/lossless-scaling.md

@@ -0,0 +1,116 @@
+<!-- Generated from the Runi source repository at v0.4.0. -->
+<!-- Edit the original there, not this copy. -->
+
+# Lossless Scaling
+
+Runi can configure [lsfg-vk](https://github.com/PancakeTAS/lsfg-vk)
+frame generation for each registered game. Lossless Scaling itself provides
+both upscaling and frame generation on Windows; the Linux Vulkan layer exposes
+the LSFG frame-generation path, not the application's scaling algorithms.
+
+## Ownership and dependencies
+
+Runi never purchases or installs Lossless Scaling, and never copies or
+distributes `Lossless.dll`. That file is proprietary, paid, and shipped inside
+a Steam application: the player buys it, Runi finds it.
+
+Runi *does* install the **layer**. The earlier rule said it would not, but
+that rule bundled two claims together and only one of them was about
+licensing; the other was consistency with how `gamescope` and `mangohud` are
+treated. lsfg-vk is free software published as a GitHub release, and
+`core/install/installer.py` already downloads and checksum-verifies
+third-party binaries - Runi had simply never installed this particular one.
+See "Installing the layer" below.
+
+The **Lossless Scaling** game tab becomes editable only when Runi finds:
+
+- a supported lsfg-vk 1.x or 2.x Vulkan layer and its shared library; and
+- Steam AppID `993090` in a native, external, or Flatpak Steam library, with a
+  readable `Lossless.dll` in that installation.
+
+Use **Recheck** after installing either dependency externally. If a dependency
+disappears while a game is enabled, the enable switch remains available so the
+saved integration can be turned off; launches otherwise fail with an actionable
+missing-dependency error.
+
+## Installing the layer
+
+```bash
+runi lossless-scaling                 # what is present, what is missing
+runi lossless-scaling install         # fetch and register the layer
+runi lossless-scaling remove          # undo, if runi installed it
+```
+
+The desktop GUI's **Lossless Scaling** tab shows the same thing and offers an
+**Install lsfg-vk** button, which appears only when no layer is registered.
+
+Runi installs the release's layer-only artifact - about 700 KB, against 74 MB
+for the bundle that also ships a configuration UI Runi has no use for, since
+it writes the layer's settings as environment variables itself. Two files are
+written, both user-level, neither needing root:
+
+| File | Destination |
+|---|---|
+| `liblsfg-vk.so` | `~/.local/lib/` |
+| `VkLayer_LS_frame_generation.json` | `$XDG_DATA_HOME/vulkan/implicit_layer.d/` |
+
+Three details are not obvious:
+
+- **The manifest is rewritten on install.** The shipped one names its library
+  as the bare filename `liblsfg-vk.so`, which the Vulkan loader resolves
+  against the system's shared-object search path - not against the manifest's
+  own directory, and `~/.local/lib` is not on that path. Runi substitutes the
+  absolute path of the library it just installed. Left alone, the layer would
+  register and then fail to load.
+- **The download is verified against the digest the GitHub API publishes for
+  the asset**, because this project ships no checksum file of its own - unlike
+  every Proton source, which publishes a sibling `.sha512sum`. Verification is
+  required rather than best-effort: this is a shared library that every Vulkan
+  application on the machine will load. An asset with no published digest is
+  refused.
+- **Runi refuses to register a second layer of the same name.** If lsfg-vk is
+  already installed - most often from your distribution's packages, in
+  `/usr/share/vulkan/implicit_layer.d/` - Runi reports where that one came
+  from instead of adding its own. Two manifests claiming one layer name is a
+  real failure mode, not untidiness. For the same reason `remove` only ever
+  deletes what Runi itself installed; a package's copy belongs to the package
+  manager.
+
+Prereleases are skipped: the 2.x line is published only as one, and it drives
+a different set of environment variables. Pass `--version <tag>` to select a
+specific release.
+
+## Per-game behavior
+
+The tab controls the displayed-frame multiplier, motion-estimation flow scale,
+performance model and the lsfg-vk 1.x experimental present-mode option.
+Native HDR is managed only in the dedicated **HDR** tab and is the source of
+truth for launch composition. lsfg-vk 1.x receives its HDR shader mode
+automatically; 2.x has no equivalent separate control and reports that limit
+instead. The legacy `hdr_mode` field remains only as a schema migration mirror.
+
+For lsfg-vk 1.x, Runi uses its documented environment-only mode. This
+avoids editing `~/.config/lsfg-vk/conf.toml` and avoids process-name matching.
+The equivalent environment interface is used for 2.x. Dedicated settings take
+precedence over duplicate LSFG values in the game's generic `[env]` section.
+
+When the integration is disabled, Runi adds no enable or disable variable.
+Profiles maintained externally with `lsfg-vk-ui` can therefore continue to
+apply. Only the main Play action receives the per-game environment; settings
+tools and other auxiliary actions do not.
+
+## Compatibility notes
+
+- The final graphics path must use Vulkan. DirectX 11/12 games normally reach
+  Vulkan through DXVK or VKD3D-Proton, while native OpenGL-only games do not.
+- Generated frames increase displayed frame rate, not game simulation or input
+  sampling. Start with a stable base frame rate and evaluate latency and visual
+  artifacts in motion.
+- Gamescope may not honor the VSync behavior expected by lsfg-vk. Verify frame
+  pacing and latency when both are enabled.
+- Native HDR should only be enabled for an active HDR game and desktop pipeline.
+- Vulkan-layer injection may be rejected by anti-cheat. Runi warns when
+  anti-cheat evidence exists and never enables Lossless Scaling automatically.
+
+The current installation state and warnings are advisory; the running game is
+the final compatibility test.