> 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/0027-console-names-in-the-emulator-catalogue.md). # ADR 0027: Console names, as plain text, in the emulator catalogue ## Status Accepted (owner overrule, 2026-09-30). The docs session will build a kouch.dev page with every emulator's profile to download, with automatic updates, and central builds the profiles. Asked how console names should appear there, the owner chose "Names, text only": real console names in plain text, to say what an emulator runs, with no logos, pictures or brand styling. The alternatives offered were emulator names only, or fully neutral names. Relaxes: ground rule 1 (no third-party console names in Kouch's own content), for the **emulator catalogue only**: its own separate section of kouch.dev (e.g. `/emulators`) and the catalogue's profile files. The rest of the site stays brand-free. Related: ADR 0006 (community emulator profiles), ADR 0009 (Workshop themes), ADR 0025 (controller icons). ## Context * A catalogue that can't say "this emulator runs " is hard to use: people look for the console, not the emulator's project name. * Sites like EmuDeck's name consoles in plain text (nominative use: saying what a thing is for). Kouch's app, store page and assets stay brand-free. * In 2023 an emulator was pulled from Steam over a platform holder's objection (about key material, not naming). Kouch's Steam presence must stay clean. ## Decision **Allowed**, only in the catalogue (the kouch.dev emulator page and profile files published for download): * console names in plain text, used only to say which system an emulator or a profile's `systems` entry runs; * emulator project names and links to the projects' own sites and releases. **Not allowed anywhere, including the catalogue:** * logos, console or controller pictures, brand colours or typefaces, box art, game titles or art; * any wording that suggests affiliation or endorsement. **A trademark footnote** on the catalogue page: "Console names belong to their owners. Kouch isn't affiliated with them or with the emulator projects." **Unchanged:** * The Kouch app, the built-in theme, Kouch's docs and guide, the Steam store page, and Kouch's own assets stay brand-free. * Brand-lint keeps enforcing that everywhere, the catalogue included. The catalogue's data (`catalog/`) and pages allow only named groups of terms (amended 2026-09-30, central, when the first profiles showed what they need): * readable text (names, labels, descriptions): the company, console and emulator groups, because official console names begin with the company's name; * an emulator's own config keys, values and paths, quoted verbatim like an SDK identifier: the controller group too, since some emulators name their settings after the pads they emulate. The lint checks each catalogue `.kod` field by field. A field counts as readable text unless it's on the lint's list of config fields, so a new field is checked strictly; * franchises, menus, online services and stores stay blocked everywhere. * Ground rule 2 still holds in the catalogue: * no ROMs, BIOS, firmware or keys, and no links to them; * no per-title rules (`game_defaults`) in Kouch-published profiles; * no game names. * A profile may name the system files it expects (ADR 0020 matching) but never where to get them. ## Risks, recorded * **A platform holder could object to the catalogue.** Answer: switch the page to emulator names only (a content change, no app change), and keep the profiles downloadable. * **Steam review could see the site as affiliated with consoles.** The store page links only to the guide, not to the catalogue page. * **The lint exception could leak into app content.** It's scoped to the catalogue paths and reviewed like any `allow:` line. ## Consequences * A `catalog/` folder of public-ready profiles: no local paths, no private data, validated by `validate_profile`, with one `allow:` path in the blocklist. The site reads it at build time or through its cached release fetch. * `docs/PROFILES_CATALOG_PLAN.md` defines what a catalogue profile must have, and how each is verified before publishing. * Kouch shows a catalogue profile's system names wherever it shows any imported profile's (Home's last-played line, Library's system tiles). Screenshots for the store page, the guide and the site therefore use the neutral mock profiles, never a catalogue profile (noted 2026-09-30, during the first catalogue verification). --- # 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/0027-console-names-in-the-emulator-catalogue.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.