> For the complete documentation index, see [llms.txt](https://docs.kouch.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kouch.dev/docs/adr/0014-steam-library-companion.md). # ADR 0014: The Steam library companion is a fork of an existing shortcut manager ## Status Accepted on 2026-09-26 (owner request: "fork steam rom manager for the images of the games, image data, game data, descriptions, information, add to steam shortcuts and launching via kouch"). It refines FEATURE\_PLAN's "Add games to the Steam library": that section already put shortcut writing in an external GitHub companion tool. This ADR settles how that tool is built and what stays in Kouch. ## Context * Each game should appear as its own tile in Steam (Big Picture and Deck Game Mode), with artwork, launching through Kouch so Steam Input, the Quick Menu, seats and sync run under Kouch. * Steam has no API for adding shortcuts. Tools write the binary `userdata//config/shortcuts.vdf` and the `config/grid/` artwork while Steam is closed, because Steam rewrites the file on exit. Kouch itself runs under Steam, so it can't close Steam and write the file. That is why FEATURE\_PLAN made this an external tool. * The owner asked to fork Steam ROM Manager (SRM), the established open-source tool that already does this well: parsers, SteamGridDB artwork, previews, categories, Steam shutdown and restart, backups, Deck Desktop Mode support. * SRM is **GPL-3.0**, TypeScript + Electron + Angular (checked 2026-09-26). ## Decision 1. **The companion is a fork of SRM** (working copy `C:\dev\kouch-srm`), and it stays a **separate GPL-3.0 program**. * No SRM code is copied into Kouch's repo or binaries. * The two talk only through a documented JSON export and Kouch's command line: an arm's-length boundary, so Kouch's own license is unaffected. * Its repo is private: `golfista/kouch-srm`, default branch `kouch` (owner, 2026-09-26: it can be public, but private is preferred). It is not a GitHub fork, because a GitHub fork of a public repo is always public. 2. **The fork adds one source: a "Kouch library" parser.** * It reads Kouch's export: `/exports/steam-library.json` (format below). * For each game it makes a shortcut whose target is Kouch's executable with `--launch=`, or later `steam://rungameid///--launch=` once Kouch's app id exists. * Artwork: Kouch's own art for the game, when it has some, is the default choice. SteamGridDB (the user's key) and SRM's other providers stay available. * Kouch's additions to the fork follow ground rule 1: no console brand names in anything Kouch adds. Upstream presets are left as they are. 3. **What stays in Kouch** (brand-free, as always): * **Stable game ids** that survive rescans. * **The export command:** Settings › Steam library › "Update the Steam library file". It also runs after every scan when that is on. * **`--launch=` on a first start.** Kouch already handles it from a second instance. When Kouch was started just for that launch, it exits after the game quits, so Steam records play time and returns to its library. * **Game information:** * description, developer, publisher, release date, genres, players and rating; * read first from the ES-DE/EmuDeck `gamelist.xml` the user already has, then from online providers the user turns on; * shown on the game page's Details tab. 4. **Writing shortcuts never happens during development on the owner's real Steam.** Tests use scratch `userdata` trees. The first live write needs the owner's go-ahead, and the companion's own backup runs first. ## Export format (`kouch-steam-library/1`) ```json { "kouch_steam_library": 1, "generated": "2026-09-26T21:00:00Z", "launch": { "target": "C:\\Program Files\\Kouch\\Kouch.exe", "start_in": "C:\\Program Files\\Kouch", "args": "--launch={id}" }, "games": [ { "id": "stable id", "title": "Title from the user's file", "system": "System name from the profile", "path": "the game file", "art": { "tall": null, "wide": null, "hero": null, "logo": null, "icon": null }, "info": { "description": null, "developer": null, "publisher": null, "release_date": null, "genres": [], "players": null, "rating": null } } ] } ``` Paths are absolute. `art.*` are files Kouch already has on disk. `system` gives the companion a category name. Nothing in the export is committed to either repo; it is generated from the user's own library. ## Consequences * The owner gets SRM's mature shortcut and artwork handling, with Kouch as the launcher, for a small fork diff: one parser plus a default for local artwork. Upstream fixes can be merged. * Two programs to ship: Kouch on Steam, and the companion on GitHub for Desktop Mode or Windows. FEATURE\_PLAN's later Decky-plugin option for Game Mode is unchanged. * The companion's GPL obligations (source for its binaries) apply to the companion only. * Risk: SRM's internals can change upstream. The parser is isolated in its own file to keep merges easy. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kouch.dev/docs/adr/0014-steam-library-companion.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.