docs: user-facing documentation and signing key

docs/technology-scan.md

@@ -0,0 +1,103 @@
+<!-- Generated from the Runi source repository at v0.4.0. -->
+<!-- Edit the original there, not this copy. -->
+
+# Technology Scan
+
+Technology Scan builds an evidence-based inventory for each game. Its guiding
+rule is:
+
+> Local analysis and PCGamingWiki are automatic; the inventory is complete;
+> Overview contains the expandable summary; runtime observation is explicit.
+> Recipe recommendations are a consequence of the inventory, not a separate
+> scanner.
+
+## Evidence sources
+
+The local scan stays inside the registered installation root. It inspects
+filenames, directory conventions, Windows PE imports, the PE version resource of
+known upscaler and frame-generation DLLs, and a bounded set of small text logs. It recognises graphics APIs, upscalers and frame generation, engines,
+audio/physics middleware, anti-cheat and DRM, and compatibility-loader
+markers (LinUwUx). It does not scan the full Wine
+prefix, follow external symlinks or unpack large game archives such as `.pak`
+files; those would introduce unrelated evidence, especially in shared prefixes.
+
+Community evidence comes from the official PCGamingWiki MediaWiki API. Runi
+queries by a known store identity before trying an exact canonical title,
+identifies itself with a project user-agent, observes the service rate limit and
+caches responses for seven days. A network failure never blocks registration or
+launch.
+
+SteamDB has no public API and explicitly disallows automated scraping. Runi
+therefore provides only an **Open in SteamDB** link for manual research.
+
+A filename identifies a technology *family*, never its version. One filename
+is shared across versions - `amd_fidelityfx_upscaler_dx12.dll` is the FidelityFX
+SDK 2.x name for FSR 3.1 and FSR 4.x alike - so the version is read from the
+binary's own version resource and reported in the finding's version field, with
+the vendor's full build string kept in the evidence line. A missing `pefile`, a
+binary without a version resource or a non-numeric version all degrade to a
+finding with no version rather than to a guess.
+
+For an FSR 4 capable upscaler DLL the scan also records which model weights are
+embedded (`fp8`, `int8`). That is evidence, not a verdict: it is what decides
+whether a game's own FSR 4 path can run on a given GPU generation at all.
+Runi does not compare it against the local hardware.
+
+Files recorded in Runi's own OptiScaler and Customize manifests are ignored
+as evidence. Installing a recipe must not make the next scan claim that the
+technology originally belonged to the game.
+
+LinUwUx-compatible-loader markers (`reflex.ini`/`reflex.dll`/`reflex64.dll`,
+`DenuvOwO.ini`/`DenuvOwO.dll`) are a dedicated `compat_shim` category, kept
+separate from `anti_cheat`/`drm` so a finding never affects
+`recommendations_for()`'s existing anti-cheat-gated OptiScaler suppression.
+`winmm.dll`/`version.dll` are deliberately excluded from this rule set even
+though LinUwUx's own detection also looks for them: both are generic
+proxy-DLL names also used by unrelated mods, including Runi's own
+OptiScaler manual-injection overrides, so a bare filename match on either
+risks a false positive. Finding a marker never enables `[linuwux].enabled`
+itself - it's informational only, the same detect-only philosophy as
+OptiScaler/Lossless Scaling.
+
+## Confidence and identity
+
+Every finding retains its source, locator and observation time. Confidence is:
+
+- `confirmed`: directly imported by the primary executable or observed at runtime;
+- `likely`: filename, secondary binary, log signature or community evidence;
+- `unknown`: no reliable signal;
+- `conflicting`: authoritative signals disagree.
+
+Community findings belong to the canonical Runi Game ID. Local files and
+runtime observations belong to the Installation ID, because another build or
+store release of the same game may differ.
+
+DRM reported only by PCGamingWiki is presented as **possible DRM** because the
+community entry may describe an older build from before that DRM was removed.
+Local or runtime evidence takes precedence when both sources are available.
+
+## Runtime scan
+
+**Run Runtime Scan** performs one diagnostic launch with Proton DLL logging and
+observes the Linux process tree through `/proc`. It does not install or inject
+Special K. Collection ends when the launcher exits or when the player chooses
+**Finish Runtime Scan**. Only matched module/signature evidence is retained;
+the complete diagnostic log is not copied into the technology report.
+
+Runtime observation can confirm that an FSR provider DLL loaded, but the FSR
+watermark remains the authority for the exact `FSR4-I8 Upscale 4.1.1` model.
+
+## Recipe recommendations
+
+- DirectX 12 plus a modular FidelityFX upscaler DLL found on disk or observed
+  at runtime recommends **Native FSR 4.1.1 Upgrade**. Community evidence alone
+  does not qualify: it names the family without proving the DLL is present.
+- Native Vulkan recommends **Generic OptiScaler + FSR 4.1.1** for DX12 interop.
+- DLSS, XeSS or older FSR without a confirmed native upgrade path recommends
+  OptiScaler.
+- Ambiguous evidence leaves the choice to the player.
+- Detected anti-cheat suppresses automatic OptiScaler recommendation and shows
+  an injection warning.
+
+Recommendations never apply a recipe automatically. One recipe remains active
+per installation.