> 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/0019-kod-carries-emulator-release-files.md). # ADR 0019: An exported emulator carries its installation sources for every platform, never install fi ## Status Accepted on 2026-09-27 (owner). ADR 0006 is unchanged: Kouch never bundles an emulator, a `.kod` never carries emulator files, and a profile is data, not code. History: the owner first asked that an export "include the original install files, like the linux, windows, macos, everything". Before any code was written they clarified: *"not the install files, but rather the installation source like a github repo"*. The first version of this ADR (packing verified release files, `a709b59`) is replaced by this one. Git keeps it. ## Context * An exported emulator should install on whoever imports it, on their OS, with the version the exporter had, without anyone sending binaries. * Profile schema v3 (`docs/KOD_PLATFORMS_PLAN.md`) already gives each OS its own section with its own `source`: a GitHub or GitLab release (repo + asset pattern), a project's feed, or Flathub. So "the installation source" for every platform is data a `.kod` can carry. * Many profiles people have today have a single OS section (v1/v2, or written on one machine), so an export from them would only reach one OS. ## Decision * **Every platform's source travels.** Exporting an emulator writes its profile with every platform section's `source`: Windows, Linux and macOS, whichever the profile has (`portable()` already keeps every section). It never includes emulator files. * **The exporter's version travels too, as a suggestion.** The export records the installed version (`exported_version`). The import sheet offers "Install 2.6 (the version this was exported with)" or "Install the latest". The choice uses the version lists (K2); nothing is pinned without the user choosing it. * **Every export covers Windows and Linux (required; owner: "not optional, required, since a linux user might want to install").** For each emulator, a supported OS without a section is filled in at export time: * **Where Kouch looks:** * the same GitHub/GitLab release's assets: `*.AppImage` / `*linux*` for Linux, `*windows*` / `*win64*` / `*.exe` archives for Windows; * for Linux, also the emulator's Flathub app, found by name, as a `flatpak` source. * **One clear match** (an x86\_64 AppImage, or a Flathub app whose name matches): added automatically and shown in the sheet, where the user can change it. * **Several matches, or an archive whose program name Kouch can't know:** the user must pick the asset and, for an archive, the program inside it. The export waits until that's done. * **Nothing matches** (the project ships no build for that OS): the sheet says *"This emulator has no Linux release. This file won't install on Linux."*, and the user confirms before exporting. * **macOS** (Kouch for Mac is a future update): added the same way when found (`*.dmg` / `*macos*`), but never required. * **Hand-installed emulators** (no source) export with their launch path. The import sheet then asks where the emulator is, and says the file has no install source. ## Consequences * An imported emulator always installs from its official release, verified as before (ADR 0006). A `.kod` stays small and data-only. * A `.kod` exported from a single-OS profile still reaches one OS unless its author (or the "fill in" helper) adds the others; the sheet shows which OSes the file covers. --- # 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/0019-kod-carries-emulator-release-files.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.