# Shell theme settings The shell theme (name, title, icon, background) has two layers: file defaults and a stored override. The file layer is `pkg/settings.json` (name `kody-os`, empty title, empty icon, background `desk`); the override layer is one storage key, `kody-os.shell.theme`, holding only the fields that differ. The effective theme is the per-field merge of the two: a field is overridden exactly when it appears in the override, and every other field falls back to the file value. The title falls back to the name when the file title is empty. ## Set semantics A set payload is a partial override (design Decision 4): - An absent key leaves that field unchanged. - A null value clears that field's override. - Title `''` clears (the effective title then falls back to the name). - Name must be a non-empty string of at most 200 characters. - Icon is a string; `''` means the stock mark, and a value starting with `` links. Capability-gate failures (unknown app, malformed slug, no declaration, or a view-only caller of set/reset) are feed-style plain 404s with no theme detail. A gated app with an invalid value gets JSON `{ ok: false, error }` (400) and writes nothing. There is no shell denial page: a request the platform does not admit never reaches these routes. ## Declaring theme access `capabilities.theme` is `{ view: boolean, set: boolean }`, next to `feeds`, `proxy`, and `manageApps` in `AppCapabilities`. Missing flags normalize to `false` at install; a definition with neither flag true is treated as not declaring theme. The declaration appears in the Store installer disclosure and in the capability-expansion confirmation gate (a theme addition on update needs confirmation). ## Settings panel The catalog `settings` app is the browser path for changing the shell theme (see the built-in Help page). It is stateless — no theme in app state, no `act()` — and is not installed by default. Each field shows its effective value with its source (file default or override). Controls: background desk/paper buttons, name/title text inputs (title blank clears), icon glyph input with a stock-mark button, per-field reset, and one reset-all button. A custom grid background or custom SVG mark shows a notice instead of an editor ("custom grid / custom mark, set via file or agent") while still offering desk/paper or glyph/stock/reset to replace it. Core controls are plain GET forms (no POST, no JS required); JavaScript may enhance in place with `format=json`, never required. Sessions ride the cookie; no `?k=` is rendered in any link or form. ## Out of scope - No grid or SVG editor in v1 (replace only, via desk/paper or glyph/stock/reset, or via file or agent). - No shell-side gate for set/reset yet (open question 1); no auto-install of Settings yet (open question 2). - No write-through cache for the override read (open question 3, answered no by the timing measurement above).