> 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/agents/decisions.md). # Decisions: the ADRs, the plans, and the owner's standing rulings Kouch's owner decides product questions; agents build and record them. Don't re-litigate what's here: reversing a recorded decision needs a new ADR, and relaxing a ground rule needs the owner's explicit overrule plus an ADR recording the risk *before* any code. ## ADRs (`docs/adr/`) | # | Decision | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 0001 | Rust core + Tauri 2 web UI | | 0002 | DSU/Cemuhook is the primary controller output; no driver required | | 0003 | OLED-first, single-accent design system | | 0004 | Three rumble paths (see also 0023 and `RUMBLE_PLAN.md`) | | 0005 | Hybrid input: Steam Input for motion, SDL for buttons/sticks while an emulator has focus | | 0006 | Emulator install and update live in Kouch, driven by community profiles | | 0007 | Relocatable emulator user data, Steam Cloud, LAN transfer and play | | 0008 | Rich data themes (no raw CSS or scripts) and a Black/White built-in theme | | 0009 | *Overrule:* third-party Workshop themes may carry system/controller imagery | | 0010 | Per-game Workshop mods, Steam netplay with matched mods, game-style settings | | 0011 | Sandboxed WebAssembly plugins | | 0012 | EmuDeck-compatible multi-disk `Emulation` folder; cloud-safe data per Steam user | | 0013 | Steam Cloud through the API only, no Auto-Cloud | | 0014 | The Steam library companion is a fork of a shortcut manager (superseded by 0016) | | 0015 | A Linux `unsafe` island so the UI follows the display refresh under gamescope | | 0016 | The Steam library integration is a first-party Kouch plugin | | 0017 | In Game Mode the Quick Menu is a same-app override window | | 0018 | Steam Cloud sync is on by default for every emulator | | 0019 | An exported emulator carries its install sources for every platform, never install files | | 0020 | *Overrule:* Kouch places system files (keys/BIOS/firmware) the user drops onto it, into the matching emulator's `system` folder; every other path still refuses them | | 0021 | The SteamGridDB key lives in the OS secret store and syncs encrypted through Steam Cloud | | 0022 | Discord as a second social backend through the Discord Social SDK (loaded at run time, never committed) | | 0023 | *Overrule:* an optional ViGEmBus rumble upgrade on Windows using the driver's second pad type: one aliased line in code, a patched vendored crate | | 0024 | A `.kod` may carry its own controller-type icons (PNG/WebP only) | | 0025 | *Overrule:* Kouch ships recognisable controller icons and Steam Controller button glyphs from Kenney's CC0 Input Prompts. Logos stripped, neutral names; a "Simple" set as a setting; Steam Controller glyphs as the default. Amended 2026-09-30: Deck d-pad, keyboard glyphs, cursors, and a few Kenney UI icons | | 0026 | At most 8 players, every one with motion (owner). Two DSU servers (26760–26761); a ninth controller waits; the connect screen tops out at 2 × 4 | | 0027 | *Overrule:* the emulator catalogue (`catalog/` and its kouch.dev section) may name consoles and emulator projects in plain text; no logos, pictures, game names or `game_defaults`. Brand-lint allows only named groups there: company, console and emulator names in readable text, plus controller names in an emulator's own config fields (amended 2026-09-30) | ## Plans (all additive: a new plan never replaces an old one) | Doc | What it covers | Status table | | --------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------- | | `FEATURE_PLAN.md` | the product: phases, pricing, security, roadmap (§2b motion remote) | — | | `ARCHITECTURE.md` | the original implementation plan and verified facts | — | | `PLAN_V2.md` | the living plan: Big Picture-style shell, themes, controllers, storage, art, options, mods, netplay, plugins | per-phase Status lines | | `HOME_LIBRARY_PLAN.md` | Home + Library redesign, fit-to-screen stage, data contract v5, Steam social | H0–H9 | | `DECK_UI_PLAN.md` | Deck-grade legibility, touch targets, highlights, Windows/Linux parity | — | | `KOD_PLATFORMS_PLAN.md` | one `.kod` for every OS, Linux/GitLab/Flatpak sources, version lists | K1–K7 | | `GAME_MENU_EXPORT_PLAN.md` | the game menu, exports, easy graphics, system-file drop | G1–G9 | | `STEAM_SCREENSHOTS_PLAN.md` | game screenshots in Steam's Screenshots view | S1–S4 | | `DISCORD_PLAN.md` | Discord friends, invites, one conversation per person, profile source | DC0–DC9 | | `VPAD_PLAN.md` | virtual pads (uinput, ViGEmBus) | V1–V5 | | `RUMBLE_PLAN.md` | rumble through Steam's virtual pads, the optional upgrade | R1–R6 | | `CONTROLLER_TYPES_PLAN.md` | controller types per console and game, automatic graphics, a later metadata server | T1–T8 | | `NAMES_AND_KEYS_PLAN.md` | clean display names, the art key in Steam Cloud | N1–N3 | | `ACHIEVEMENTS_PLAN.md` | Steam achievements, "Beat a game" through RetroAchievements, daily streaks | AC0–AC10 | ## The owner's standing rulings (from conversations, not in an ADR) * **The stack stays Rust + Tauri + Svelte.** An ES-DE fork only comes back if the Deck gate fails. * **Build autonomously; report milestones, not questions.** Ask only for decisions that are genuinely the owner's (product direction, a ground-rule exception, anything touching their accounts or hardware). * **Plans are additive:** new plans go in new docs. * **Test through Steam.** A direct or Start-menu launch gets the owner's desktop controller layout ("it does unexpected stuff"). * **Never restart Steam** (it asks for their account). * **No stick dead zone or dead-zone setting in Kouch:** Steam Input handles it. * **Updates stay opt-in per emulator.** * **Display names** come from the database, embedded metadata or a cleaned file name, and Kouch never renames the user's files. * **Nothing agents run makes a sound** unless the owner is testing. * **Controller icons are Kenney's flat CC0 icons, scaled up** for the connect screen and the Quick Menu. Button glyphs default to the Steam Controller set, with the d-pad from the Steam Deck set (2026-09-30), and keyboard prompts use Kenney's keyboard glyphs. * **UI icons stay Kouch's own line set** (2026-09-30, after a side-by-side comparison, ). The exceptions are players, friends, online play and chat, which use Kenney's, plus new Kenney icons: signal bars, cloud, tilt, trophy, ranking, recenter, locked. * **Cursors:** the motion pointer is a Kenney hand per player. The mouse cursor is Kenney's shaded triangular arrow everywhere, and it doesn't switch to a hand over clickables, unless that hand is drawn in exactly the arrow's style; any such hand is shown to the owner first (owner, 2026-09-30). * **Rumble:** through Steam's virtual pads by default. The rumble pad is bound as an *output only*, so it never interferes with input. The ViGEmBus upgrade is optional and never downloaded by Kouch. * **Home's wide card uses Steam's hero shape (1920×620);** covers use 600×900; the row's first card uses the 920×430 wide grid. * **The mouse expands Home's regions** on a short rest (dwell), the way focus does. * **Achievements** (2026-09-30, `ACHIEVEMENTS_PLAN.md`): "Beat a game" comes from RetroAchievements, reading the username from the emulator so there's no second sign-in. Dropped: a seat taken mid-game, hosting a lobby, sending a chat message, playing on a handheld, resuming on a second device after a Cloud sync, switching themes, making a collection, importing someone's profile, publishing to the Workshop, playing with motion controls on, shaking the controller in a game, a controller dying mid-game, and playing together past midnight. Streaks count days Kouch is opened, across every PC on the account, with no reminders. The owner writes the names and descriptions in the plan's Steamworks templates; keep their text as they wrote it. * **Metadata server and performance reports:** later, opt-in and anonymous, after an ADR and the owner's server/API. The owner (2026-09-30) listed what reports would carry: the frame rate while a game runs, system info and RAM, and controller info. Kouch's public promise is **"No tracking without your permission"** (it was "No analytics, no tracking"). Until reports ship, nothing is sent at all. **Order:** the server and the reports come only after the current goal round is done and fully polished (owner, 2026-09-30). * **Players:** at most 8, every one with motion (ADR 0026, 2026-09-30). The recommendation given was a CDN for the metadata (Cloudflare R2 or Bunny) and a small ingest endpoint + queue + ClickHouse for reports. --- # 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/agents/decisions.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.