Release architecture: separate Linux image, TrainerOS software and OddCrate game updates #153

Product decision

TrainerOS is no longer tied to one flashed Linux image. It is a portable, self-contained gaming environment distributed both in a prepared image and via the convergence installer on existing SteamOS/Bazzite Linux hosts (#70/#118).

Separate the release/update ownership boundaries instead of using 'OS update' for everything:

Image and software have distinct version numbers and manifests. A new image carries a pinned compatible software snapshot for clean first boot, but later TrainerOS software updates can proceed without reflashing, rebuilding or updating the Linux base. A Linux image update must not downgrade already newer compatible TrainerOS software accidentally.

ROM Policy Studio's signed encrypted data is a TrainerOS-software release component: an urgent policy-only software update can change only policy files/signatures/manifest, without rebuilding application/emulators/images (#140/#142/#143). This remains the ordinary TrainerOS software update channel, never an independent policy downloader.

User journeys

1. Prepared image device: optional System image update for the managed Linux base; frequent TrainerOS software update for shell/features/runtime/policies; OddCrate game updates separately.
2. SteamOS/Bazzite install: host OS updates in normal host tools, TrainerOS software updates from TrainerOS, and OddCrate games update separately. TrainerOS never replaces/rolls back the host OS.
3. Hotfix: release a tiny signed policy-only TrainerOS software update; no image rebuild, emulator reinstall, download of unchanged files or independent list updater.

Safety and compatibility

• Shared software manifest describes architecture, device capability, compatible host OS interface range, runtime/core/adapter bundle identity, own paths/services, policy version and data migrations.
• Host-image and TrainerOS software updater must coordinate compatibility and live-session safety, avoiding updates during protected game/save activity.
• Signed integrity, atomic stage/apply, repair and last-known-good software rollback are distinct from OS A/B rollback.
• Persist game ROMs, BIOS, saves, play history, Trainer data, OddCrate installs and user-owned host files across both update types.
• Host update/drift detection uses Maintenance: audit and repair TrainerOS after host OS updates #123 and never resolves incompatibility by taking over SteamOS/Bazzite.

Related issues

• Distribution: build a reproducible TrainerOS system image on top of ArmadaOS #70 prepared image; Prepared-image OS updates: base Linux OTA independent of TrainerOS Software #71 owned image/base OS update.
• Distribution: add a convergent TrainerOS installer for SteamOS and Bazzite #118–Acceptance: prove image and installer converge to the same TrainerOS experience #125 convergence installer, runtime and equivalence.
• Distribution: independent image and TrainerOS software release manifests and ownership #119 separate image and software release ownership/versions.
• Guest ROM policy: signed official-release prohibitions and user content responsibility #140/Private tooling: ROM Policy Studio authoring and signing workflow (never commit editor to GitHub) #142/Distribution: ship signed ROM policies via TrainerOS SOFTWARE updates, including policy-only releases #143 software-delivered guest-ROM policies.
• OddCrate: curated free games, self-hosted builds, creator support and community ratings #144/OddCrate installer: integrate install, update and removal with the existing TrainerOS game library #148 OddCrate independent content updates.

Acceptance

• Image can remain at base version I while software advances S→S+1 and features become available without reimaging.
• SteamOS/Bazzite software update uses same S+1 artifacts and TrainerOS-owned runtime compatibility, with unchanged host boot/OS.
• Image base I→I+1 update does not reinstall/downgrade unrelated already-compatible user/game/software state.
• Signed policy-only S+2 update installs no changed binary, emulator/core or OS base.
• Three distinct version identities and update histories/statuses are understandable in settings.
• Interrupted/failed updates recover at the correct ownership layer.
• OddCrate game updates and ordinary host OS updates remain fully independent.

Implementation checklist

• TrainerOS Software: signed cross-distro updater independent of system image #154 — cross-distro signed TrainerOS Software updater (independent of image I/host H)
• Settings UX: show separate System Image, TrainerOS Software and game updates #155 — controller-first Updates UI separating image, software and OddCrate game updates
• TV UI foundation: introduce a real ten-foot responsive layout system, not 960x540 stretching #156 — shared true responsive Handheld/TV layout foundation
• TV UX: redesign Home, libraries, OddCrate, Social and game overlays for couch viewing #157 — TV re-composition across primary screens and all relevant overlays
• TV input UX: reliable D-pad/remote focus, text entry and accessibility at ten feet #158 — couch controller/remote focus, typing and accessible input
• TV display profiles: external screen, docked mode and safe transition without host takeover #159 — dock/TV output detection and safe display-profile transitions
• Acceptance: independent image/software updates and true handheld/TV parity across install modes #160 — release/update + handheld/TV acceptance matrix

Existing issues corrected

• Distribution: build a reproducible TrainerOS system image on top of ArmadaOS #70/Prepared-image OS updates: base Linux OTA independent of TrainerOS Software #71 — prepared image and base-Linux OTA only
• Distribution: add a convergent TrainerOS installer for SteamOS and Bazzite #118–Acceptance: prove image and installer converge to the same TrainerOS experience #125 — installer/software-equivalence and host-update repair
• Platform: reusable device, external-display and TV presentation profiles #78 — external-display, TV profile and independent release-channel capabilities
• Guest ROM policy: signed official-release prohibitions and user content responsibility #140/Private tooling: ROM Policy Studio authoring and signing workflow (never commit editor to GitHub) #142/Distribution: ship signed ROM policies via TrainerOS SOFTWARE updates, including policy-only releases #143 — ROM policy is signed TrainerOS Software payload, not base-image OTA
• OddCrate: curated free games, self-hosted builds, creator support and community ratings #144/OddCrate UX: discovery, curated collections and game detail inside Multiverse #145/OddCrate: show verified creator donation links as QR codes, with no in-app payments #150/OddCrate acceptance: real game discovery, self-hosted release, donation and qualified reviews #152/Adventure Reviews: universal 2-hour-or-completion ratings, stars and comments for every game #113/UX acceptance: validate the complete Social → Together → party → game → return journey #135 — TV-responsive discovery, social, QR donations and reviews

Implementation order

1. Distribution: independent image and TrainerOS software release manifests and ownership #119 release ownership, TrainerOS Software: signed cross-distro updater independent of system image #154 software update and Settings UX: show separate System Image, TrainerOS Software and game updates #155 Settings presentation in parallel with TV UI foundation: introduce a real ten-foot responsive layout system, not 960x540 stretching #156 responsive layout tokens.
2. TV UX: redesign Home, libraries, OddCrate, Social and game overlays for couch viewing #157/TV input UX: reliable D-pad/remote focus, text entry and accessibility at ten feet #158 UI and focus reflow; TV display profiles: external screen, docked mode and safe transition without host takeover #159 external display handling.
3. Acceptance: independent image/software updates and true handheld/TV parity across install modes #160 verifies actual devices, distinct-version update flows and preservation.