docs: user-facing documentation and signing key

docs/launch-providers.md

@@ -0,0 +1,126 @@
+<!-- Generated from the Runi source repository at v0.4.0. -->
+<!-- Edit the original there, not this copy. -->
+
+# Launch providers, emulated games and auxiliary actions
+
+## Status
+
+This describes the implemented provider model for Windows executables,
+wrapper bundles, emulated games and shared storefront clients.
+
+## Architecture
+
+Launch construction has three independent dimensions:
+
+```text
+Launch target -> provider -> execution engine -> optional wrappers -> process
+```
+
+- A **target** is Play, Settings, Open Emulator or another explicit action.
+- A **provider** builds the program invocation: direct executable, Xenia,
+  RPCS3 or Ubisoft Connect.
+- An **engine** runs that invocation: Proton/UMU, direct Proton or the Linux
+  host. `host` is deliberately distinct from the legacy runtime backend named
+  `native`, which means direct Proton.
+- Gamescope, MangoHud and CPU affinity wrap Play by default. Utility actions do
+  not inherit graphical wrappers.
+
+Examples:
+
+| Use case | Provider | Engine |
+|---|---|---|
+| Existing Windows game/wrapper | executable | Proton/UMU or direct Proton |
+| Xenia with an ISO | xenia | Proton |
+| RPCS3 with a PS3 game directory | rpcs3 | host |
+| Windows Settings tool | executable | inherited Proton engine |
+| Open emulator UI | executable/emulator UI | provider's engine |
+| Ubisoft game deeplink | ubisoft | shared Proton prefix |
+
+## Persistence and compatibility
+
+Schema v3 added `game.platform`, `game.install_root`, `[launch]` and repeated
+`[[actions]]`. Schema v5 adds `[store_binding]` and store-specific identity
+aliases. Schema v7 separates a port's original platform from its target OS
+and stores optional Lossless Scaling frame-generation settings. Schema v8 adds
+explicit OptiScaler provider and migration state. Schema v9 adds managed native
+HDR state and migrates the legacy Lossless Scaling HDR option. Schema-v2 files remain
+readable and map to Windows, direct
+executable provider and Proton engine. Merely reading/listing does not rewrite
+them; the first later save creates a `.toml.v2.bak` and writes v9.
+
+Every existing v2 game must produce the same argv, environment and working
+directory after loading through the new model. Recipes, prefix bundles,
+Doctor, saves, artwork, notes and configuration edits remain compatible.
+
+## Library hierarchy
+
+The primary navigation is platform, followed by a scoped store filter:
+
+```text
+All | PC | Windows Ports | Linux Ports | Xbox 360 | PlayStation 3
+      All stores | Steam | GOG | Epic | Ubisoft | Local
+```
+
+Only populated platform/store values appear. Search and sort apply after both
+filters. Store and platform remain independent; emulator is neither. An Xbox
+360 ISO imported from disk is initially `platform = "xbox360"`,
+`store = "local"`. Disc/digital format may become a separate future field.
+
+Port collections are derived from `port_target_os`, while `platform` retains
+the original/content platform. A Windows port keeps Proton, Windows Technology
+Scan, recipes and OptiScaler. The first curated example is Gears of War 2 -
+Hollow (`xbox360 -> windows`); see its
+investigation (source repository). Linux Ports is structural in
+this phase: ELF/AppImage import and host launch remain future work.
+
+## Add/import experience
+
+Selecting a file or folder runs conservative local detection and shows the
+platform, evidence, confidence and additional actions before registration.
+Recognized Xenia bundles use the included wrapper by default and offer direct
+Xenia as an alternative; an existing wrapper is never silently replaced.
+`Settings.exe` and the Xenia UI become Settings and Open Emulator actions using
+the same prefix.
+
+RPCS3 imports read `PS3_GAME/PARAM.SFO`, resolve title/Title ID and build a host
+launch without Proton. A later library importer can batch-select games from an
+RPCS3 installation. Runi detects existing emulators or accepts a custom
+path; the first phase does not install/update them.
+
+## Process and safety rules
+
+- Process tracking keys auxiliary work by `(game_id, action_id)`; Play/Stop
+  remains tied only to the primary target.
+- Settings and Open Emulator are unavailable while Play owns the same prefix.
+- Relative target paths resolve below the explicit install root. Importers do
+  not create arbitrary command strings.
+- Providers own argument ordering and validation.
+- Adapter-suggested save paths require user confirmation; no backup starts
+  automatically.
+- Multi-disc metadata may be retained, but interactive disc switching is a
+  later phase; existing wrappers continue owning it.
+
+## Shared storefront sessions
+
+Ubisoft games reference a versioned store installation instead of owning a
+Wine prefix. The shared installation owns the prefix, launcher path and Proton
+runner; changing its runner updates every linked game. Play sends
+`uplay://launch/<id>/0` to `upc.exe` and monitors the detected game executable,
+not merely the short-lived deeplink process. After that executable exits,
+Runi allows 30 seconds for cloud sync before closing the managed session;
+**Keep Open** cancels automatic closure. Concurrent games in the same store
+prefix are refused, removal of one game never removes the shared prefix, and a
+per-game prefix bundle cannot include it. See [ubisoft-connect.md](ubisoft-connect.md).
+
+## Delivery and acceptance
+
+1. Schema-v3 compatibility and golden launch-plan regression tests.
+2. Provider/engine boundary with executable and host execution.
+3. Auxiliary action model, CLI and GUI process tracking.
+4. Xenia and RPCS3 providers plus conservative detection.
+5. Platform -> Store library filters and reviewed Add flow.
+6. Real acceptance: existing registered Windows titles, Lost Odyssey wrapper,
+   direct Xenia and one RPCS3-native title.
+
+No phase is accepted while an existing game's launch plan changes
+unintentionally.