> 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/profiles_catalog_plan.md). # The emulator catalogue: well-built profiles, published on kouch.dev (2026-09-30) An addendum to `PLAN_V2.md`, `KOD_PLATFORMS_PLAN.md`, `CONTROLLER_TYPES_PLAN.md` and `PROFILE_AUTHORING.md`. It doesn't replace them. ## What the owner asked for > "@kouch documentation will have the auto updates, and will have all the emus on that page to download, you will build perfect profiles" * **The docs session:** the emulator catalogue as **its own section of kouch.dev** (owner: "this will be its own separate section"; e.g. `/emulators`, apart from the main pages), with one entry per emulator and a download of its `.kod`. Also the site's automatic updates. * It deploys on every push through Cloudflare Workers Builds' GitHub connection (no GitHub Actions). * Emulator versions come from the emulators' own release feeds, fetched and cached (about an hour) by the site's Worker. * **Central:** the profiles, built and verified here, published from `catalog/`. * **Console names:** plain text only, per ADR 0027. ## What a catalogue profile must have (the "perfect profile" checklist) 1. **Sources for every OS it runs on:** * Windows and Linux (AppImage/release and/or Flathub); * a `macos` section only when the emulator has a macOS build; * `origin` set to the profile's home. * Versions list correctly (`emulators_versions`), and install works from the UI (not only the backend; see FINDINGS #50). 2. **Fullscreen:** borderless by default (the Quick Menu draws over it), using the emulator's own setting where it has one. Verified by the launcher's window check. 3. **Controllers:** * DSU/motion configured per player through `{dsu_host}`/`{dsu_port}` config edits, for all 8 players (ADR 0026); * motion wherever the emulator reads it. * The console's controller types as a `controller` option with Kenney pictures, the console's usual controller as the default, and the bindings each type writes. * No `game_defaults`: per-title rules stay out of Kouch-published profiles (ground rule 2). 4. **Rumble:** the profile's `rumble` section where the emulator can rumble an SDL pad (RUMBLE\_PLAN). 5. **Graphics:** * options with roles (`internal_resolution`, `anti_aliasing`, `anisotropic`, `renderer`, `aspect`, `vsync`, `docked_mode`…), presets, and `auto` hints, so Automatic picks well on a handheld, a laptop and a desktop; * dual-screen consoles get layout options (the default is a large main screen with the small one beside it). 6. **Hotkeys:** quit (graceful), pause, screenshot, save and load state where supported, fullscreen, plus `hotkeys.extra` for anything worth a Quick Menu button. 7. **User data:** `saves`, `states`, `screenshots` and `config` mapped into Kouch's layout (Steam Cloud on). The screenshot folder feeds Steam's Screenshots view. 8. **System files:** named for ADR 0020 matching (the file names the emulator expects), never where to get them. A profile that needs them says so plainly and refuses to launch without them. 9. **Mods and netplay** where the emulator supports them: a `mods` section and a `netplay` adapter. 10. **Audio:** a `volume` option, so Kouch can set the emulator's volume (and a test run can mute it). Added 2026-09-30 (FINDINGS #58). 11. **Clean:** * no local paths, no private data, no game names; * `validate_profile` passes; * schema v3; * the version bumped when anything changes. ## How each profile is verified before it's published * **Import the catalogue `.kod` into a fresh isolated instance, launched through Steam** (the Kouch Dev `verify` route): * install from the UI; * launch a real game the owner already has (read-only, never copied), or, for a system the owner has no game for, check the written config files only; * check the DSU client registered, motion and buttons (the dev virtual pad), fullscreen, the emulator's own screenshot, a graceful quit, and each controller type's rewritten config. * **Linux:** the same on the Deck in Game Mode (the Flatpak or AppImage source). * **Recorded** in `EARLY_TESTS.md` ("Catalogue profile: ") and a status table below. Only verified profiles go into `catalog/`. ## Order 1. **The four already verified** (the owner's library: the pointer console, tablet console, dual-screen handheld and hybrid console), cleaned into catalogue form. 2. **The widely used standalone emulators, one system family at a time**, starting with systems where the owner has games to test with. The system-files catalogue's list (`profiles/local/system-files.catalogue`, 53 emulators) is the pool. 3. **Anything else the owner names.** ## Audit of the first four (2026-09-30, `scripts` audit against the checklist) The private test profiles on main, before catalogue work. "dsu edits" counts `{dsu_port}` uses. "user data" counts saves/states/screenshots/config. game\_defaults must be 0 in the catalogue. | profile | win/linux src | origin | fullscreen | dsu edits | ctrl types | rumble | gfx roles | presets | auto | hotkeys | extra | user data | system files | mods | netplay | game\_defaults | | -------------------- | ------------- | ------ | ---------- | --------- | ---------- | ------ | --------- | ------- | ---- | ---------------------------------------- | ----- | --------- | ------------ | ---- | ------- | -------------- | | reference | ✓/✓ | ✗ | fullscreen | 1 | 4 | ✓ | 6 | 3 | ✗ | pause screenshot save\_state load\_state | 0 | 4/4 | ✗ | ✓ | ✗ | 1 | | tablet console | ✓/✓ | ✗ | borderless | 7 | 2 | ✗ | 4 | 3 | ✗ | screenshot | 0 | 3/4 | ✗ | ✓ | ✗ | 0 | | dual-screen handheld | ✓/✓ | ✗ | borderless | 1 | 1 | ✗ | 5 | 3 | ✗ | pause screenshot save\_state load\_state | 2 | 2/4 | ✗ | ✓ | ✗ | 0 | | hybrid console | ✓/✓ | ✗ | borderless | 178 | 2 | ✗ | 7 | 3 | ✓ | pause screenshot | 0 | 4/4 | ✓ | ✓ | ✗ | 0 | Corrections from B (checked in the profiles themselves): all four already name their system files and map all five user-data folders. The audit script missed the ADR 0020 names and folders mapped through links; a console without save states has states n/a by design. **Rumble** is only possible where the emulator can rumble a pad separate from its DSU input: the reference emulator can; the tablet console, hybrid console and dual-screen handheld can't (recorded per profile, after checking the installed versions). **Where the catalogue lives publicly:** `origin: {kind: "url"}`, pointing at `https://kouch.dev/emulators/.kod`, with `https://kouch.dev/emulators/index.json` ({id: {version, revision, sha256}}) generated from `catalog/` at build time. An update check reads the index, compares version then revision, and verifies the sha256 before replacing a profile (https, same host, no redirects; updates stay opt-in). The Kouch repo stays private. Gaps to close before these four go into `catalog/`: * `origin` on all four; * the reference profile's one `game_defaults` entry stays in the private test profile only, not in the catalogue copy; * Automatic `auto` hints on the reference, tablet-console and dual-screen profiles; * `rumble` where the emulator can rumble an SDL pad; * the tablet-console profile's hotkeys beyond screenshot, and its fourth user-data folder; * the dual-screen profile's missing user-data folders; * a `netplay` adapter where the emulator has netplay; * system-file names where the emulator expects them (ADR 0020 matching). ## Status | Item | Who | Status | | ------------------------------------------------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ADR 0027 (console names, text only) | central | written with this plan | | `catalog/` folder, brand-lint scoping, validation in the gate | central + B | done: lint groups (`19c608f`), the four profiles + gate test `committed_profiles.rs` (`c55250c`, `a911b26`), field-by-field lint of each `.kod` (`0b2cba4`, fails closed, `--self-test`); reviewed by central | | First four profiles in catalogue form, verified | central | **Windows done** (EARLY\_TESTS "Catalogue profiles, Windows half"): 4 of 4 pass, with FINDINGS #57 (tablet-console resolution), #58 (volume), #59 (dual-screen seat 1). The Deck half next; the reference profile's second system has no game to boot here | | Disc-console family (the pool's first tier, B) | B + central | two built (`c8a4e73`, `818ee04`): checked on Windows through Steam (install, portable config in Kouch's layout, refusal without system files, graceful quit). No boot here (no games or system files for that family); seat binding waits for a real pad press. The third (the handheld one) is B's next. Deck half pending | | #57 tablet-console resolution through the game's own graphics pack | B | verified live (`56d8a43`) | | kouch.dev emulator page, deploy on push, cached version fetch | docs session | next | --- # 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/profiles_catalog_plan.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.