fix(steam): follow recommended Proton runtime (#198)

## Summary
- follow Darktide-specific and global Steam compatibility-tool mappings
before falling back to the appinfo `recommended_runtime`
- collect the recommendation and Valve-managed tool registry in one
bounded appinfo scan while preserving authoritative invalid mappings
- add reusable Steam Deck OS-release identity detection without coupling
it to Proton selection
- update Steam architecture, reference, and Steam Deck documentation
with regression coverage for the live appinfo shape

## Verification
- `dotnet build src/modificus-curator.sln --configuration Release` (0
warnings)
- `dotnet test src/modificus-curator.sln --configuration Release` (1,855
passed)
- `dotnet format src/modificus-curator.sln --verify-no-changes`
- `git diff --check`

Author: ModifAmorphic

AGENTS.md

@@ -882,9 +882,20 @@ src/        Modificus Curator -- the mod manager app (.NET 10 + Avalonia 12)
                         IProfileService.GetModList)
   steam/                Modificus.Curator.Steam -- Steam + Darktide + Proton discovery
                         (multi-library + compatdata; Linux Proton resolves from Steam's
-                        CompatToolMapping in config.vdf to a custom compatibilitytool.vdf
-                        or a Valve-managed appinfo/appmanifest install, never a directory-name
-                        guess; Steam text KV1 parsing centralized through SteamTextVdf with
+                        CompatToolMapping in config.vdf, app-specific entry first then
+                        the global "0" entry, to a custom compatibilitytool.vdf
+                        or a Valve-managed appinfo/appmanifest install, never a
+                        directory-name guess; with neither mapping, Darktide's appinfo
+                        recommended_runtime (the steam_deck_compatibility metadata) is
+                        Steam's non-user default on any Linux host (one appinfo.vdf
+                        scan collects both the compat_tools registry + the
+                        recommendation; an invalid/unreadable mapping or a
+                        native/missing recommendation fails unresolved without falling
+                        through); Steam Deck identity (SteamDeckDetector +
+                        SteamDiscoveryOptions.IsSteamDeck, detected from OS release
+                        metadata ID=steamos + VARIANT_ID=steamdeck, host file first)
+                        is a generic platform identity input, not Proton policy;
+                        Steam text KV1 parsing centralized through SteamTextVdf with
                         HasEscapeSequences always on, ValveKeyValue 0.70.0.499), the
                         ISteamService.Discover automatic/manual mode policy + Rediscover
                         forced-automatic surface, IsGameRunning (WinProcessLookup
@@ -1002,6 +1013,13 @@ src/        Modificus Curator -- the mod manager app (.NET 10 + Avalonia 12)
                                           atomic missing-only persistence) + the
                                           ModDisplayMetadataMapper normalization
     Modificus.Curator.Steam.Tests/           xUnit tests for discovery + IsGameRunning
+                                            (incl. the Proton selection precedence: app-specific,
+                                            global, invalid-entry no-fall-through, + the appinfo
+                                            recommended-runtime fallback end-to-end, identical
+                                            regardless of Deck identity; the appinfo reader
+                                            one-pass snapshot against a realistic multi-entry
+                                            fixture matching the live shape; + the OS-release
+                                            Deck detector)
     Modificus.Curator.RelayClient.Tests/ xUnit tests for the launch façade (dual-purpose:
                                             `dotnet test` = xUnit; `dotnet run` = composition smoke harness);
                                             covers RelayLaunchServiceTests (Windows + Linux arg
@@ -1264,7 +1282,7 @@ dotnet run   --project src/ui --configuration Release   # app shell window
   boundary; ordered env-var entries + game args; validated up front via the
   shared `LaunchSettingsValidator`, applied at launch; `GetLaunchSettings` is the
   focused read the launch path uses),
-  **Steam** (Steam + Darktide + Proton discovery via Steam's CompatToolMapping + the automatic/manual mode policy + `Rediscover` + `IsGameRunning`),
+  **Steam** (Steam + Darktide + Proton discovery via Steam's CompatToolMapping with the appinfo recommended-runtime fallback + the automatic/manual mode policy + `Rediscover` + `IsGameRunning`),
   **Integrations** (the Nexus v1 client/auth +
   `IModAcquisitionService` the download + extract + place orchestrator +
   `IUpdateCheckService` the Nexus-only update-check service +

STEAMDECK.md

@@ -52,8 +52,10 @@ Do not force a Proton compatibility tool on the Curator shortcut. Curator is a
 native Linux app. It launches Darktide through the game's own Proton
 environment: in automatic discovery mode (the default), Curator reads the
 Proton tool Steam has selected for Darktide and uses that, so changing Darktide's
-compatibility tool in Steam is all you need to do. The Curator shortcut itself
-always stays native.
+compatibility tool in Steam is all you need to do. If Steam has no explicit
+selection for Darktide, Curator follows the runtime Steam records as recommended
+for Darktide in its app metadata. The Curator shortcut itself always stays
+native.
 
 Because the installer writes one stable AppImage path, the Steam shortcut stays
 valid across Curator's in-app updates.

docs/architecture/MODIFICUS-CURATOR.md

@@ -667,8 +667,11 @@ Responsibilities:
     Steam's `CompatToolMapping` (the app-specific entry for Darktide is
     authoritative; the global entry is the fallback), then resolving that tool
     name to a `proton` binary from a custom `compatibilitytools.d` manifest or a
-    Valve-managed install. This follows Darktide's own Steam compatibility
-    selection rather than guessing from directory names.
+    Valve-managed install. With neither mapping, Darktide's appinfo
+    `recommended_runtime` is Steam's non-user default on any Linux host; an
+    invalid or unreadable mapping fails rather than bypassing a possible user
+    choice. This follows Darktide's own Steam compatibility selection rather
+    than guessing from directory names.
   - **Escape hatch:** when auto-discovery can't resolve any of the above,
     prompt the user for the missing path(s). This is possible only because
     discovery lives in the UI app, not in Relay (which has no UI and could

docs/reference/steam.md

@@ -88,8 +88,12 @@ every OS-specific input + platform seam is injected:
   Notable fields: `LinuxDefaultSteamRoot`, `LinuxFlatpakSteamRoot`,
   `LinuxCompatibilityToolsDir`, `LinuxSystemCompatibilityToolsDirs` (the two
   standard Steam system directories, defaulting so `/usr/share/steam/compatibilitytools.d`
-  is searched), `WindowsDefaultSteamRoot`, `DarktideAppId` (`1361210`),
-  `DarktideCommonDir`, `GameBinaryName`, `GameProcessName`.
+  is searched), `IsSteamDeck` (a platform identity input: whether the host is a
+  Steam Deck; `CreateDefault()` detects it from OS release metadata --
+  `ID=steamos` + `VARIANT_ID=steamdeck`, reading `/run/host/os-release` before
+  `/etc/os-release`; tests can inject a fixed value), `WindowsDefaultSteamRoot`,
+  `DarktideAppId` (`1361210`), `DarktideCommonDir`, `GameBinaryName`,
+  `GameProcessName`.
 - `ISteamDiscoverer` (internal) -- `Discover() → DiscoveryResult`. The
   platform-specific discovery strategy. Two implementations
   (`LinuxSteamDiscoverer`, `WindowsSteamDiscoverer`), selected once at DI time
@@ -104,15 +108,24 @@ every OS-specific input + platform seam is injected:
   composition, not inheritance -- each discoverer injects the core and layers its
   own platform steps on top.
 - `ProtonResolver` (internal) -- the Linux Proton compatibility-tool resolver,
-  constructed by `LinuxSteamDiscoverer`. Reads Steam's `CompatToolMapping` from
-  `config.vdf`, then resolves the selected tool name to a `proton` binary as a
-  custom tool (a `compatibilitytool.vdf` manifest) or a Valve-managed tool
-  (appinfo + appmanifest). See [Linux Proton resolution](#linux-proton-resolution).
+  constructed by `LinuxSteamDiscoverer`. Reads Steam's tool selection (the
+  app-specific `CompatToolMapping` entry, then the global `"0"` entry, then the
+  appinfo recommended runtime when both mappings are absent), then resolves the
+  selected name to a `proton` binary as a custom tool (a
+  `compatibilitytool.vdf` manifest) or a Valve-managed tool (appinfo +
+  appmanifest). See [Linux Proton resolution](#linux-proton-resolution).
 - `SteamAppInfoReader` (internal) -- parses Steam's binary `appinfo.vdf`
-  container (versions 39-41) and extracts the first app entry carrying a
-  `compat_tools` collection. Used by `ProtonResolver` for Valve-managed tool
-  resolution. Has an internal `ReadCompatTools(Stream)` overload so tests feed a
+  container (versions 39-41) in one scan that collects the first app entry
+  carrying a `compat_tools` collection and the requested app's recommended
+  runtime (either may be absent; a requested app id of 0 skips the runtime
+  lookup so the scan stops at the first registry). Used by `ProtonResolver` for
+  Valve-managed tool resolution + the no-user-mapping runtime fallback. Has an
+  internal `ReadSnapshot(Stream, requestedAppId)` overload so tests feed a
   synthetic binary fixture.
+- `SteamDeckDetector` (internal static) -- the production Steam Deck detection
+  behind the `SteamDiscoveryOptions.IsSteamDeck` platform identity input (see
+  above). Quoted values are tolerated; IO/access failures degrade to "not a
+  Deck".
 - `SteamTextVdf` (internal static) -- the single entry point for Steam text KV1
   parsing (`config.vdf`, `compatibilitytool.vdf`, `appmanifest_*.acf`). Wraps
   ValveKeyValue with `HasEscapeSequences = true` always on (Steam files
@@ -222,32 +235,52 @@ flipping the mode.
 
 ### Linux Proton resolution
 
-`ProtonResolver` reads the tool Steam actually selected for Darktide, rather
+`ProtonResolver` resolves the tool Steam actually selected for Darktide, rather
 than guessing from directory names. The steps are best-effort: a missing or
 unreadable file degrades to an unresolved Proton (warning), never a throw.
 
 1. **Selected tool name** -- `<steamRoot>/config/config.vdf` →
-   `Software > Valve > Steam > CompatToolMapping`. The app-specific mapping for
-   Darktide's app id (`1361210`) is authoritative when present; its `name` is
-   used as-is, and an empty or malformed name fails resolution without falling
-   through. The global `"0"` mapping is consulted only when the app-specific
-   mapping is absent. No mapping at all → unresolved.
+    `Software > Valve > Steam > CompatToolMapping`, with this precedence:
+    - The app-specific mapping for Darktide's app id (`1361210`) is
+      authoritative when present; its `name` is used as-is.
+    - The global `"0"` mapping is considered only when the app-specific mapping
+      is absent, and is authoritative when present.
+    - Only when both are absent, Darktide's appinfo
+      `common/steam_deck_compatibility/configuration/recommended_runtime` is
+      Steam's non-user default and supplies the name on any Linux host; host
+      identity (Steam Deck or not) is not consulted for this decision.
+    - A present mapping whose `name` is missing, non-string, empty, or
+      whitespace is **invalid**: resolution fails without falling through (this
+      covers both the app-specific and the global entry, and an invalid
+      app-specific entry blocks the global entry too). Likewise, a selected
+      mapping whose named tool cannot be resolved stays authoritative and never
+      falls through to the recommendation, and a `config.vdf` that exists but
+      cannot be read or parsed fails unresolved rather than bypassing a
+      possible user choice. A missing config file, or a valid config with
+      neither key, counts as no user mapping and permits the recommended-runtime
+      fallback.
+    - A missing, empty, whitespace, `native`, or unresolvable recommendation
+      yields unresolved with a warning; no other runtime is guessed.
 2. **Custom tool** -- a `compatibilitytool.vdf` manifest whose `compat_tools`
-   collection defines the selected name, searched across every
-   compatibility-tool root in order: the resolved Steam root's
-   `compatibilitytools.d`, the configured user root, then the system roots
-   (including `/usr/share/steam/compatibilitytools.d`). Each root is checked
-   root-level first (Valve permits a manifest directly at the root with a
-   relative or absolute `install_path`), then its per-tool subdirectories. The
-   resolved `install_path`'s `proton` file must exist.
+    collection defines the selected name, searched across every
+    compatibility-tool root in order: the resolved Steam root's
+    `compatibilitytools.d`, the configured user root, then the system roots
+    (including `/usr/share/steam/compatibilitytools.d`). Each root is checked
+    root-level first (Valve permits a manifest directly at the root with a
+    relative or absolute `install_path`), then its per-tool subdirectories. The
+    resolved `install_path`'s `proton` file must exist. This runs first for any
+    selected name, including the recommended runtime.
 3. **Valve-managed tool** -- the `compat_tools` entry in
-   `<steamRoot>/appcache/appinfo.vdf` (binary; parsed by
-   `SteamAppInfoReader`) whose key or comma-separated alias matches the selected
-   name, then `appmanifest_<appid>.acf` across the libraries, parsing its
-   `installdir`, requiring
-   `<library>/steamapps/common/<installdir>/proton` to exist.
+    `<steamRoot>/appcache/appinfo.vdf` (binary; parsed by
+    `SteamAppInfoReader`) whose key or comma-separated alias matches the selected
+    name, then `appmanifest_<appid>.acf` across the libraries, parsing its
+    `installdir`, requiring
+    `<library>/steamapps/common/<installdir>/proton` to exist. One `Resolve`
+    call parses `appinfo.vdf` at most once: when the recommended runtime
+    supplies the name, the snapshot already read for the recommendation is
+    reused here.
 4. Nothing resolves → `null` (escape hatch; UI prompts). A reason is appended to
-   `Warnings`.
+    `Warnings`.
 
 `ProtonVersion` carries the tool's `display_name` when present (the custom
 manifest's, or the appinfo entry's), otherwise the internal tool name.
@@ -399,10 +432,15 @@ no-op).
 `Modificus.Curator.Steam.Tests` covers Linux discovery (`LinuxDiscoveryTests`,
 `FlatpakDiscoveryTests`), Windows discovery (`WindowsDiscoveryTests`), Proton
 compatibility-tool selection (`ProtonSelectionTests`, `ProtonResolverTests` --
-app-specific vs global mapping, custom vs Valve-managed tool resolution, root-
-level vs subdirectory custom manifests, system roots), the binary
-`appinfo.vdf` reader (`SteamAppInfoReaderTests`, against a compact synthetic v41
-fixture with a string table), the `SteamTextVdf` escape-semantics helper
+app-specific vs global mapping vs the appinfo recommended-runtime fallback
+(identical regardless of Deck identity) and every blocking rule around it,
+custom vs Valve-managed tool resolution, root-level vs subdirectory custom
+manifests, system roots), the binary
+`appinfo.vdf` reader (`SteamAppInfoReaderTests`, against compact synthetic v41
+fixtures plus a realistic multi-entry fixture matching the live appinfo shape --
+Darktide's `recommended_runtime` + the Steam Play manifest's `compat_tools` in
+both entry orders), the Steam Deck OS-release detector (`SteamDeckDetectorTests`), the
+`SteamTextVdf` escape-semantics helper
 (`SteamTextVdfTests`, including a sanitized realistic `config.vdf` fixture with
 an escaped JSON scalar), the `libraryfolders.vdf` parser
 (`LibraryFoldersVdfTests`), game-running detection (`GameRunningTests`,