> 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/0024-kod-bundled-controller-icons.md).

# 0024: A .kod may carry its own controller-type icons

* Status: accepted (owner request, 2026-09-29: the controller types "have to be nice icons, these can be with the .kod file, or bundled in with the .kod profile")
* Plan: `docs/CONTROLLER_TYPES_PLAN.md` (T2, T3)
* Extends: ADR 0009 (third-party Workshop themes may carry device imagery) to `.kod` profiles

## Context

Emulator profiles gain controller types: the ways a console's controllers can be held or combined, picked per emulator and per game (`CONTROLLER_TYPES_PLAN.md`). The owner wants each type shown with a good icon on the game page and in the picker.

* Ground rule 1 keeps third-party console imagery out of Kouch's own code, assets and docs.
* ADR 0009 already lets third-party Workshop themes carry device imagery.
* A community `.kod` is the same kind of third-party content, written by whoever maintains that emulator's profile, not by Kouch.

## Decision

* **Kouch ships only neutral, in-house icons** for the generic controller classes, drawn like the connect screen's silhouettes and brand-free, and profiles can name them.
* **A `.kod` may carry its own icons** under `icons/` in its zip.
  * **Format and size:** PNG or WebP only (no SVG, so nothing can script), at most 256 KB per file and 64 files.
  * **References:** the profile refers to an icon by a relative path inside the `.kod`. Validation refuses anything else: remote URLs, absolute paths, `..`, and other file types.
  * **Serving:** the files are extracted into the profile's own data and served through the scoped `kmedia` protocol, like theme assets.
* **What Kouch itself carries:**
  * Kouch never downloads icons, never names or links to an icon source, and doesn't commit third-party icons.
  * The private test profiles in `profiles/` may carry icons while the repo is private; they're a GO\_PUBLIC\_CHECKLIST item, like their other private data.
  * Exporting a `.kod` carries the icons the imported profile came with, the same as its other data.

## Consequences

* A community `.kod` can show real controller images in Kouch. The risk is the same as ADR 0009's: store-policy exposure if Kouch were seen to ship them. Kouch doesn't: it only displays what a user imported.
* The validator gains an image check (type sniffed from the bytes, not the extension; dimensions capped) that the theme path can share.
* The neutral set must be good enough on its own, since most profiles will use it.


---

# 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/0024-kod-bundled-controller-icons.md?ask=<question>&goal=<endgoal>
```

`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.