> 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/history.md).

# Project history (the old "Current state" log)

Moved out of `CLAUDE.md` on 2026-09-30, verbatim, so CLAUDE.md can keep a short current snapshot. Newest entries are at the bottom. Commit SHAs refer to `main`; the per-phase status also lives in `docs/PLAN_V2.md`, `docs/HOME_LIBRARY_PLAN.md` and the other plans' status tables.

Test totals at the last full runs: 1012 Rust on Windows and 822 UI at `e1b4156` (2026-09-29), 919 in the Linux build container (xvfb) at `84eded0` (2026-09-27). fmt, clippy, check, design-lint, brand-lint and build all clean. Plan v2 progress per phase is tracked in `docs/PLAN_V2.md` (the Status lines); the bullets below are the highlights.

* **Milestone 0 done** (`d5d9419`): workspace, UI scaffold, lint, CI, docs, milestone issues #1–#13.
* **Milestone 1 / Early Test 0 PASSED 2026-09-17** on 5 controllers incl. the 2026 Steam Controller — the window + Steam-parent conditions in "Running the real app under Steam". **Steam Direct submitted 2026-09-17**, identity verification ≤ 10 business days.
* **Early Test 1 measured 2026-09-17:** child-window focus stops Steam Input actions (0/65) but not `GetMotionData` (4860/4960 ticks) → hybrid input (ADR 0005).
* **Milestone 3 (`kouch-dsu`) done 2026-09-17**; **Milestones 2, 4 and the Rust half of 5 done 2026-09-18 (`aa75bc2`)**: input thread, SlotManager, profiles, library, Windows launcher, Tauri shell implementing the full IPC contract.
* **UI (Milestones 5–9) visually verified 2026-09-18 (`f2b7b5a`→`1f270db`)** at 1280×800 / 1920×1080 / 3840×2160 / 2560×1080 / 150 %; shell matched to the contract (`73bac45`).
* **First end-to-end run under Steam 2026-09-18 (`e140be3`→`088a945`):** Steam Input up, 4 pads auto-claimed, scan → tiles → launch of a stand-in emulator → overlay over its window with routing frozen → graceful + force quit → focus restored. Early Tests 9 PARTIAL, 11 and 12 PASS. Fixed from the run: a pad seated twice by SDL + Steam (merged-key seating), SDL opened after a failed Steam init, navigator pinned to P1, `Player.connected` while frozen, sheets not taking focus, empty-library Settings unreachable, `set_size` on a hidden window, on-accent text, silent refused launches.
* **Owner's second feature set 2026-09-18 (`76803a5`→`cfb1d56`), verified live:** fixed 5×3 library grid (DESIGN.md §4); Steam user in the status strip + profile card (`kouch-steam::profile` → `steam:user`); community emulator profiles with in-app install/update/rollback (`kouch-updater`, ADR 0006 — supersedes FEATURE\_PLAN's external updater; the user still adds every emulator, Kouch never bundles one); multiple game folders per system (library schema v2).
* **User data, Steam Cloud, LAN transfer + LAN play done 2026-09-18 (ADR 0007), verified live where one PC allows:** five prefilled user-data folders, ini `config_edit` with backup/restore, `system_folder_present`, cloud sync "skipped" under the borrowed id, LAN discovery bind + accept-side LAN filter (fix `9a58d20`). **Unverified live:** real Steam Cloud write (needs Kouch's app id); a second *physical* PC for LAN (two instances on one PC pass discovery, pairing, transfer and co-op since `6214866` — `docs/EARLY_TESTS.md`).
* **Download queue with progress UI 2026-09-19**, real GitHub release install verified live (92 progress events); **`.kod` container 2026-09-19** replacing `.koe/.koes/.kom/.koms`, then refined to the single-extension rule (`0daf281`); **motion remote (`MotionRemote`) added to the roadmap** (FEATURE\_PLAN §2b, Phase 3) — estimate 3–4 weeks, third `HidSource` over hidapi, IR pointer as virtual mouse, Deck first.
* **Mouse + keyboard parity 2026-09-19 (`dad8cea`, `9c8e9e4`):** compact Steam profile sheet with X + scrim-tap close, X on every sheet, clickable prompt bars everywhere, keyboard on the real transport (was mock-only). Verified with real CDP key/mouse events against the Steam-launched app.
* **Verified with the dev virtual controller 2026-09-26 (`KOUCH_DEV_VPAD=1`, `kouch-lab vpad`):** claim by A, Make Player 1 (LT), the Quick Menu chord, pad navigation in the Quick Menu, hold-to-confirm quit, buttons and motion in a real pointer game (centred at rest, correct directions after `525b1ee`).
* **Still owner-only:** a real pad's feel (tilt and buttons by hand), a real emulator profile (Early Tests 4, 9 exclusive-fullscreen, 12 save hashing), lab tests `reconnect-order`/`dsu-reorder`/`dsu-disconnect`/`motion-reassign` (unplugging pads), two-PC LAN, real Steam Cloud, the motion remote (roadmap only).
* **Plan v2 Phase 3 controllers + Phase 4 wizard UI, 2026-09-26 (C):** code complete.
  * **Connect screen.** Hero → 1×4 → 2×4 → pages with FLIP (`lib/flip.ts`). Every waiting pad shares one outlined square whose silhouette and Join glyph cycle once a second (`f29a8f8`). Re-grip happens in Reorder.
  * **Silhouettes and drive icons.** Generic in-house set from `app/ui/scripts/gen-silhouettes.mjs`.
  * **Pad metadata.** SDL3 battery/link on every pad and in the DSU battery byte. Each pad also carries its Remote Play session.
  * **Nav.**
    * New actions: X/Y/View/LT/RT.
    * `InputCmd::UiNav` makes pads navigate Kouch's own window; before this they only drove the Quick Menu. The shell turns it off while a game runs.
    * Buttons already held when a seat starts are swallowed.
  * **Keyboard + mouse seat.** `KeyboardSource` over Raw Input (`source/rawinput_win.rs`), verified with injected input via `kouch-lab kb-seat`.
  * **Glyphs.** Steam glyphs per family (`glyph_get`) plus a style setting; prompts read the glyph store from context.
  * **Settings › Controllers.**
  * **Split-pair pairing.** Pure, in `source/splitpair.rs`, gated by `KOUCH_SPLIT_PAIRS=1` until a hardware check. The SDL hint names are quoted only in `source/sdl_hints.rs`.
  * **Wizard + Settings › Storage,** including saves → Steam Cloud with undo.
  * **Still hardware-only:** split-pair, keyboard seat in an emulator, live glyphs, pad nav of the main window.
* **Plan v2 Phase 4 storage core 2026-09-26 (`432e821`, `24e9158`, B):** `StorageLayout` in `kouch-profiles/src/storage/` is the one resolver for user data, installed emulators, mods and media (legacy `<data>` paths until `settings.storage.main` is set). `ensure_layout` is create-only and idempotent (startup, import, wizard, Repair). `saves\<emu>` is a junction into `<config>\cloud\<steam id>`; `system` maps to `bios\<emu>`, never inside the cloud folder. Moves are hash-verified and never read `bios`. `Launcher::spawn` takes a resolved `UserDataContext`. Tested only on temp dirs + a scratch EmuDeck tree; the drive list saw the owner's `R:\Emulation` read-only.
* **Plan v2 profile schema v2 + Phases 7/8 backend 2026-09-26 (`6e3de41`, `6f345c5`, `6382243`, B):**
  * `systems[]` accepts objects (`folder`/`name`/`art.thumbnails`); new `data_folder`, `options`, `option_values`, `mods`, `netplay` fields; profile version 2.
  * Per-game options layer at launch (`options::apply_options`).
  * Mods: `kouch_launch::mods` applies and reverts them around a session from a manifest written *before* each change (startup reverts leftovers). A mod is data only, and one refused file refuses the whole mod.
  * The ground-rule deny-list scan exempts only Kouch's own `{placeholders}` (`validate.rs` `is_known_placeholder`).
* **Plan v2, 2026-09-26 (kouch central):** first real-emulator run (ffa8ea7): a private test profile installs the reference emulator from its own release feed (new `json_feed` source + `.7z`), configures DSU/motion via ini `config_edits`, 42 games scanned from the owner's `R:\Emulation`, a game launched fullscreen and quit gracefully twice; fixes found there (DSU ini name, NKit dialog, `window_mode`, auto-claim ignoring connected pads, claimed pads losing their kind, hotkeys without focus). Then: automatic art (bf7f413; 42/42 titles matched), sandboxed WASM plugins (`crates/kouch-plugins`, 626d993/7d86331, `docs/PLUGIN_AUTHORING.md`, sample in `examples/plugins/`), Steam netplay (`crates/kouch-netplay` + `app/src-tauri/src/netplay.rs`: lobbies carry the game hash and mods, loopback relay over Steam networking), Remote Play Together (21b77df, the any-emulator online path), the shared Workshop surface (f56eef1), `app.exit`. **Blocked on the owner:** Steam is running as administrator, so the Steam-launched Kouch is elevated and can't be restarted by agents — re-testing with seated pads, live motion and the emulator screenshot waits for the owner to close it. Workshop, lobbies, invites and Remote Play Together need Kouch's own app id.
* **Plan v2 Phases 1–2, the shell (A, 2026-09-26; `2e347ac`, `715bbcf`, `77dabba`):** native feel (scoped `kmedia` protocol + WebP thumbnails, no white flash, F11/auto-fullscreen, window-state, sheet transitions, frame-time HUD) and the Big Picture-style shell (Home, Library tabs/sort/grid + classic view, game page, main menu, quick access, Black/White, ambient background, 13 sound slots + generated music). Verified by CDP screenshots at every required size in both schemes. **Open:** the Deck performance gate.
* **Plan v2, later 2026-09-26:** theme engine (`theme_pack.rs`, `docs/THEME_FORMAT.md`, `theme_create`, sample `examples/themes/night-sky`) + Settings › Theme picker/extras (A); Workshop publish sheet (C); SDL3 motion fallback when Steam has none (C, |a| = 1 g over DSU without Steam); keyboard+mouse seat, split-pair, glyphs (C); boot robustness + launch-failure hardening (B); Linux build container + launcher, workspace clippy/tests green on Linux (B, `scripts/linux-build.ps1`); Windows release build + SteamPipe layout (A, `scripts/build-release.ps1`, `docs/RELEASE.md`); `{dsu_host}`/`{dsu_port}` placeholders; Steam floating keyboard (`text_input_show`). **Verified live on the isolated-build route** (no Steam): import → install → scan → art → launch → emulator screenshot hotkey → Quick Menu → per-game options (3× resolution confirmed in the emulator's own screenshot) → plugin quick save → graceful quit; pads seated and read over DSU. **Open:** live Steam Input + motion through Steam (owner must close the elevated Kouch), the Deck gate, Linux in-game hotkeys/window discovery (C); controller text entry + theme maker done (A).
* **Alpha release candidate, 2026-09-26 (kouch central acceptance):** `scripts/build-release.ps1 -Installer` builds a 32.6 MB depot (Kouch.exe, SDL3.dll, vcruntime140.dll, steam\_api64.dll, the action manifest) and an 8.8 MB NSIS installer. Silent install → run (embedded UI, pads, DSU fallback ports, no `steam_appid.txt` written) → `app_report_bundle` (no personal data) → `app_exit` code 0 → silent uninstall leaves nothing. Since then: controller text entry + theme maker, Settings › About + first-run tips (A), Steam Cloud engine (B, ADR 0013), `user_data.private` (B), LAN fixed and verified two-instance (kouch central + C), Linux AppImage/.deb smoke (B), Linux hotkeys/windows (C). Tester guide: `docs/ALPHA.md`. Release candidate `b58fe8a` accepted after the live Steam session (in-game input under Steam fixed: Steam stops Kouch's actions while an emulator has focus and hides pads from SDL, so Kouch overrides Steam's SDL ignore list, `b2c1dbb`; Steam Controller views pair, `a7213f7`; SDL stick rest dead zone; Make Player 1; seat file no longer set aside at every start, `9d06bc7`/`c75bd15`; re-import keeps the installed emulator, `2cbcd2a`). Earlier: `ee9ba39` accepted (Kouch.exe everywhere, build hash in diagnostics, no app id outside Steam, first-run wizard can't be escaped by the menus and offers "Set up later" → tips → Home "Set up now"; install → run → report → exit 0 → uninstall leaves no folder, key or shortcut). 628 Rust, 466 UI tests. **Open for the alpha:** live Steam Input + motion (owner closes the elevated Kouch), hardware unplug runs, a Deck, Kouch's own app id (Workshop, netplay invites, Remote Play, Cloud).
* **Hardening + emulators, later 2026-09-26:** two independent code reviews, every finding fixed (LAN peer names now single safe segments and case-insensitive system/bios checks `040c413`; report scrubbing; crash-safe save restore/move; launch claim reset guard; Sheet scopes popped by identity; hotplug scenario suite with 4 identity/motion bugs fixed; DSU rumble delivered to the seat). Four local test profiles now set up their emulators automatically and were verified live on isolated builds (launch, DSU client registered, screenshot read back, graceful quit): the reference one plus one for each of the three other systems in the owner's library (the one needing the owner's own system files refuses to launch until the owner's own system files are in `{system}`). New profile features: xml `config_edit`, folder games, `user_data.links` (private), `user_data.system_required`, `{key:/}` placeholders.
* **Windows release build (A, 2026-09-26):** `scripts/build-release.ps1` → `dist/windows/` (Kouch.exe + steam\_api64.dll + SDL3.dll + vcruntime140.dll + `steam/kouch_actions.vdf` = 31.5 MB; NSIS installer 8.4 MB; the script fails on any imported DLL the depot lacks) and SteamPipe scripts; `--no-default-features` drops `dev-borrowed` (now a `kouch-app` feature, default on); release builds never write `steam_appid.txt`. Smoke-tested with `KOUCH_NO_STEAM` + temp dirs + identifier `app.kouch.smoke`: embedded UI, Home/Library/Settings, Night Sky theme, Power › Exit. `docs/RELEASE.md` has the SteamPipe steps and the app-id checklist. Empty states now give one reason and one action (no emulators / drive unplugged / no games); `?mock=no-emulators|no-games|offline|no-pads|no-workshop` shows each in a plain browser. Controller text entry: `TextRow` asks Steam's floating keyboard, else opens `components/OnScreenKeyboard.svelte` (its pad shortcuts go through `FocusManager.pushInterceptor`); dev builds on the mock expose `window.__kouchMock` so screenshot drivers can send pad input. Settings › About: version + build hash (`KOUCH_GIT_HASH`, set by `build-release.ps1`), diagnostics, "Create a report for the Kouch team" (`app.report_bundle`), `app.open_folder {logs|reports}` (shell-resolved folders only), the tester guide inline, and the first-run tips (`components/FirstRunTips.svelte`: after the wizard, once per machine via localStorage, reopened from About).
* **Steam Deck, real Game Mode, 2026-09-26/27 (kouch central driving; fixes by A, B, C).** The dev AppImage runs as a non-Steam shortcut on the owner's Deck OLED (SteamOS 3.8, gamescope 3.16, 90 Hz). Test rig: `~/kouch-dev` on the Deck; see the memory `deck-game-mode-rig` (gm-run rounds, full-composition `gamescopectl` captures, the WebKit inspector over ssh, runtime CSS-injection A/Bs, source-mapped profiles).
  * **Games and the Quick Menu:** games launched from Kouch were black because emulators inherited app id 480 from Kouch's Steam init (`9ffbc23`, Steam's launch ids restored for children). The Quick Menu is a same-app override-redirect panel with pinned size hints (`dcc19eb`, `6b9a3bb`, ADR 0017; Early Test 10 PASS).
  * **Emulators on the Deck:** children get the host environment, not the AppImage's (`70ba93e`) or Steam's scout runtime (`88272d3`); Flatpak windows are found through the X-Resource pid (`ddf54ce`); `flatpak run` options go before the app id (`f478405`). A plain `kind: flatpak` profile launches, gets the Quick Menu and quits gracefully, and a Flatpak emulator registers as a DSU client (Early Test 14 PASS).
  * **Input:** the keyboard + mouse seat works on SteamOS through X raw input (`b7c1f4b`, review fixes `47a37c5`; evdev alone only reads the handheld's own devices). Steam stays up for glyphs and features when Kouch's action set can't load under a shortcut (`2169a07`). Text entry: Steam's floating keyboard can't attach to a shortcut, so Kouch opens its own controller keyboard there (`e8d9197`, `f17f3e5`, `settings.controllers.text_entry`); Steam + X still works by hand.
  * **Speed at 90 Hz (Game Mode):** library 85–87, connect \~85.5, sheet 86–87, Home 87, ambient 90 against a bar of 85.5 fps; a library step takes \~13 ms from press to screen, a Home step \~8.5 ms; first paint 1.0–1.7 s (was 6 s). What did it: one gliding focus ring instead of per-card focus transitions (`c7b0257`, `78d0b29`, DESIGN.md §4.1), transform-only FLIP keyframes (`d708c86`), a warm GStreamer registry per version (`2089c65`, `ea9c3e9`), an audio keep-alive (`1ea9772`). p95 two-frame spikes (\~5 % of frames) remain and are accepted for the alpha (PLAN\_V2 Phase 1 has the measurements).
  * **Round two on the Deck (`f29a8f8` dev AppImage, Game Mode):** pads and Steam are up 0.2–0.36 s after start, before the window's first paint (1.0–1.7 s), since `0daa9ca`; the Quick Menu draws over the game with the new prompt order. A/B against the previous build (`deck-ab.sh`, two runs each, alternating): library 84.6/85.2 vs 84.3/85.7, connect 85.4/85.3 vs 85.4/85.0, Home 88.2/87.2 vs 86.3/86.8, sheet 87.9/86.7 vs 86.1/87.2, ambient 90 both — no regression from the prompt bar, sound, join or glyph changes; the library sits at the bar as before.
  * **Still open on the Deck:** the Decky plugin's live run (`integrations/decky`, waits for the owner's OK to install); restoring the Deck's original `shortcuts.vdf` from `~/kouch-dev/backup/` and removing the "Kouch dev test" shortcut when Deck testing ends.
* **Windows, 2026-09-27 (owner at the PC):**
  * Release candidates `dd28cde` and `d87fc7c` accepted (install → run → report → exit → uninstall: no program folder, uninstall key or shortcut left; settings and the webview's data folder are kept). `build-release.ps1` works from a fresh clone (`5c6dc31`).
  * Under Steam (verify build): the 2026 Steam Controller shows Steam's glyphs (family fallback, `2169a07`), and emulators get the shortcut's own launch ids (`9ffbc23`).
  * Found live by the owner and fixed:
    * one d-pad press moved twice when Kouch was started outside Steam, because Steam's desktop controller configuration also sends arrow keys (`767b41b`, the focus manager drops a same-action press from the other source within 100 ms);
    * closing the main window left Kouch running headless with the controller ports held (`d512f7d`: close exits; during a game it quits the game gracefully first);
    * the setup wizard showed `[object Object]` for profile v2 systems (`280cb0e`).
  * B also fixed the Steam library apply, which would have reopened app 480 instead of Kouch's shortcut (`e8d9197`, `kouch_launch::launch_var`).
  * Closing the window with its X verified live: "main window closed: exiting", no process left (`d512f7d`).
  * **Second round, the installed release build under a non-Steam shortcut (as testers run it; `next-test.txt` = `rc`, `f13e3ed`).** Found live and fixed:
    * pads did nothing for \~9 s after start: Steam bring-up (a 3.2 s manifest retry + a 5 s action-set wait that can never succeed under a shortcut) ran before the input thread's first tick. Steam now attaches across ticks and the waits only apply where a manifest can load (`0daa9ca`): pads live 0.7 s after launch;
    * sounds twice: a blocked move played move + error, B closing a panel back + sheet\_close; one press now plays one cue (`456effb`);
    * the 2026 Steam Controller borrowed the original controller's colour-coded glyphs (they look like a letters-layout pad's); it now wears the handheld's monochrome set (`fb98a53`, `7e31051`);
    * prompts sat in different places per screen: one `PromptBar`, bottom-right, fixed order with B rightmost (`4fb24e6`, DESIGN.md §7);
    * Home's "Add an emulator" opens the import directly (`8b8b1af`); a waiting pad joins with A from any screen (`a4b72c2`); "start Kouch from Steam" notice outside Steam (`d5e1a43`, off the UI thread `e0b5dfb`).
  * **Next, asked by the owner:** a new Home and three switchable Library styles, chosen from C's concept canvas; motion controllers as per-player pointers (C, API agreed with A).
* **Home + Library redesign started 2026-09-27** (`docs/HOME_LIBRARY_PLAN.md`, `39d8125`). The owner's final canvas and requests: a consistent GUI everywhere, very smooth animation, many widget options, every screen fitting the whole display, and working Steam friends and chat. The owner's screens are off, so we verify ourselves (fit metrics, screenshots, the Deck perf tour, the release build under Steam).
  * **A:** the fit-to-screen stage for every screen (setup wizard first), then Home (26-widget catalogue, 260 ms fold/widen, Edit Home), then Library (Systems / Grid A–Z / Shelf / Playtime, collections, tags), then the Playtime section.
  * **B:** the app-480 guard (done, `64a1cd6`), then data contract v5: sessions/playtime, tags, collections, drive presence, update status, device power, captures, and mock art.
  * **C:** the friends feed, lobby peek and Join chip, in-app Steam friends chat (`SetListenForFriendsMessages`), lobby chat, and the social widgets and sheets.
  * **Central:** the plan, contract review, `scripts/ui-shoot.mjs` + `fit:` metrics, Deck perf phases, and the release build under Steam (`rc`).
  * **The docs session:** the user-facing GitBook guide.
* **Home + Library redesign built, later 2026-09-27** (status table in `docs/HOME_LIBRARY_PLAN.md`; DESIGN.md §3/§4/§4.1/§4b rewritten in `0a91b54`).
  * **Stage and whole pixels:** every screen fits the display and sits on whole pixels (`lib/stage.ts`, `lib/fit.ts`, `lib/pixel.ts`; `7038bcc`, `abf8bee`, `ee67822`). Checked with `scripts/ui-shoot.mjs` `fit:` + `align:`: bands ≤ 0.12, 0 near misses, 0 sub-pixel crisp boxes, 0 under the prompt bar, across the sizes, White and 150 %.
  * **Home:** the widget column with all 26 widgets (C's social/device/play ones plus A's stats/library ones), the last-played card in three styles, the row types and a second row, the strip types, the 260 ms fold/widen, Edit Home with the grouped catalogue and widget settings. Commits `c72023c`…`0c5be2d`.
  * **Library:** sections (Systems · Collections · Playtime · All games), Systems tiles with states, Grid A–Z with the letter rail, Shelf, Playtime view, the View picker, order and filter per system, unplugged drives, C's Collections (shared via `.kod`, from tags, Emulators last) and Playtime sections, and the tags sheet. The Classic, Carousel and List views are retired. Commits `b58a89d`…`13b10ef`, `faff177`, `a5067d4`.
  * **Data (B, contract v5):** sessions/playtime, tags + libretro metadat + SteamGridDB icons, collections, drive presence (offline ≠ missing), automatic scans, `emulators_list.update`, `device_power`, captures, the light list for 10k games (\~30–45 ms), and mock art. The Quick Menu now **pauses the game** (Job Object suspend on Windows; SIGSTOP to every descendant on Linux).
  * **Steam social (C):** the friends feed (verified live on the owner's account under 480: 135 friends, presence, avatars), lobby peek, Join chip and join checks, per-friend invites, in-app friends chat and lobby chat, and the friend and chat sheets. Chat send, invites and a peeked lobby still need a second Steam account to test live.
  * **Controllers:** pads send press/long/release (`14fa329`), so hold A on Play works from a controller. A waiting pad joins with A on any screen (`a4b72c2`). One outlined Join square (`f29a8f8`).
  * **Verified live:**
    * the real-emulator regression on all four test profiles (`2af9c3a`, EARLY\_TESTS);
    * the Deck in Game Mode at 90 Hz (see the next bullet for the current numbers).
  * **Since landed:** the card menu (hold X: tags / collections / finished / hide / game page, `d66c44a`), "Other files" replacing the catch-all tile, Boot advancing when Home's data is in (`8ccafea`), every sheet's "(A) Select".
* **Deck perf, the afternoon of 2026-09-27 (central profiling with a source-mapped AppImage, `wk-timeline.mjs` + `wk-map.mjs`; H9 in HOME\_LIBRARY\_PLAN has the detail):**
  * Fixed from the profiles: the Library sort (`localeCompare` with options builds a collator per call in JavaScriptCore → one `Intl.Collator`), letters from `sort_key`, batched whole-pixel reads (`scheduleFit`), prompt bars kept built. The sheet went from 82 to 88.
  * **The tour had been measuring the wrong screens:** the Deck's test settings remembered the All games section and a Playtime view, and every test title started with the same letter. The tour now starts on the Systems tiles and restores what it changes (`48838b6`, `e6482c8`), and the Deck's stand-in files span 29 letters. When a tour number looks too good or too bad, check `library.section`/`views` in the test settings first.
  * **Closed later that day:** the A–Z focus ring now snaps when a step scrolls (`39c2f7f`, found by a Deck CSS A/B) → library\_az 86.1–86.3; the hidden Home widgets no longer re-fit on seat changes (`a79a07e`). Every Game Mode phase is over 85.5 fps in both tours except one connect tour at 84.5 (alpha-acceptable). Post-RC: the View-switch max frame (A) and connect's FLIP hitches (C).
* **Alpha release candidate `6e58762` accepted 2026-09-27 (kouch central):** the installed release build under a non-Steam shortcut (`rc`) boots, shows Home/Library/quick access with the owner's Steam user and friends, writes a report with neutral controller classes (`b45a525`), and exits with code 0 and no Steam socket left open (`4a73ec5`). The full-app UI sweep is all green, 0 of 938 cells failing (C, `docs/UI_SWEEP.md`, re-run before every release). The gate at `61202bd` was 801 Rust on Windows, 805 on Linux and 696 UI; one timing-sensitive input test was hardened (`0f5b853`). The Linux Steam depot is the extracted AppImage tree (`65528d0`, `19e3cbb`, `docs/RELEASE.md` has the Deck checklist).
  * **Needs the owner:** confirm the license (`LicenseRef-proprietary` for now), a maintainer email for the .deb, which Steam account is the second one for chat/invites/peeked-lobby joins (the Deck's "haruka" also plays elsewhere; not used until the owner says), the Decky plugin install OK, and Kouch's own app id (Workshop, Cloud, Remote Play Together, rich presence).
  * **Startup:** the AppImage's squashfs costs \~470 ms of first paint per warm launch (extracted: 1.1 s vs 1.6 s), so the Linux Steam depot ships the extracted tree (B), and AppRun sets `APPDIR` itself. The Quick Menu's webview is now created after first paint (`6891a73`); an early open after a `--launch` start works in Game Mode.
* **Complete `.kod` transfer, evening of 2026-09-27** (the owner's goal: a `.kod` carries emulators, their settings, per-game settings, mods and chosen data to another system, which picks what it takes; status in `docs/GAME_MENU_EXPORT_PLAN.md` and `docs/KOD_PLATFORMS_PLAN.md`).
  * **Built:** the Graphics sheet (G6, A `d07528d`); export + import part by part, all emulators at once (G7, B `94a7515`, A `413de85`); game ids + versions, mods keyed by `{title_id}` (G8, B `a926d9a`); a file without this OS's section still imports its data into an installed copy, an installed Flatpak, the same project's build, or none (K7, B `09eb39c`, A `c979c36`).
  * **Passed live, Windows → Deck → Windows** (`profiles/local/g7-rt.kod`, a dummy game file, no manual step): the exported version's build for each OS installs; saves, config, emulator values, per-game values and a mod arrive; game data waits for the scan and applies by title id; the mod sits in the title id's folder during the session and is reverted after. K7's installed-copy, data-only and Flatpak-detection cases passed on the Deck.
  * **Found live and fixed (B `fd316e2`):** `emulators_upsert` and `settings_set` dropped every field they didn't name (the id reader, graphics presets, the clipboard/export-folder, auto-check and Steam screenshots switches). Both now merge the whole argument, guarded by round-trip tests.
  * **All emulators at once, passed live:** the four test emulators exported together from Windows (each given its Linux source; two release AppImages, two Flathub apps) and imported in one go on the Deck: AppImages installed at the exported versions, Flathub ones saved without touching the Deck's Flatpaks, settings and saves for all four. Found there and fixed: a same-named file manager was the "clear" Flathub pick (B `8dc20a6`; an installed Flathub app is now adopted, never installed twice).
  * **G9 system-file drop (ADR 0020), verified live with dummy files:** B `6715756`, A `eb944b7`/`b37425a`/`d40379c`, catalogue `profiles/local/system-files.catalogue` (53 emulators, placement only). **G2** (one game's `.kod`): contract `51ede2d`, sheets A `5fc087d`; B's shell side (with id transforms in globs) next, then the art contract and A's Change artwork. The tester pack now covers Windows and Linux (`23fcc60`).
* **Release candidate `04a4faf` accepted 2026-09-27 evening (kouch central).**
  * **Windows:** the installed build under the Kouch Lab shortcut (`rc`) boots with the owner's Steam user and friends. The setup wizard fits this PC's 7 drives at 1280×800 (C, `04a4faf`; fit/align clean) and "Set up later" keeps storage unset. The new tester pack installs all four test emulators. Reports get unique names (B, `44e2ce3`). Exit code 0, and uninstall leaves no program folder, key or shortcut.
  * **Deck (Game Mode, 90 Hz, A/B against the previous RC, two rounds each):** no phase regressed, and the View switch's worst frame went from \~90 ms to \~60 ms (A, `07c82a3`). connect stays at 83–85 fps, as before, and is a post-RC item (C).
  * **Independent review** of the transfer code: 1 high and 3 medium findings, all fixed (B `e7299a3`, central `79640f7`).
  * **Done after the RC (2026-09-28):**
    * Linux sections for the four test profiles (C's work, pushed by central in `5d69188`), verified on the Deck for three emulators: each writes into Kouch's `config`, and the owner's folders were untouched.
    * Session-only system files (ADR 0020 follow-up, B `f00cb73`), verified live on Windows (session copy, export exclusion, crash revert) and on Linux.
    * The connect-phase fix (A `59be9db`, the base screen and ambient rest under a layer). Deck A/B in Game Mode against RC 04a4faf, two rounds each: connect 86.4/85.3 vs 85.1/84.1 fps with fewer hitches, sheet 88.6/87.2 vs 86.8/86.8, every other phase unchanged.
    * Kouch applies no stick dead zone (owner: Steam Input does that; `b3f357c`): the Settings › Controllers slider and the SDL rest zone on game input are gone, and menus step at a fixed halfway point.
  * **Still needs the owner:** the SteamGridDB half of Change artwork (their key), and installing the fourth emulator's Flathub app on the Deck.
* **Deck-grade UI, 2026-09-28** (`docs/DECK_UI_PLAN.md`): `ui-sweep --deck 1` checks Valve's text floor (9 px capitals at 1280×800), 44 px touch targets, overlaps, and highlights (missing, off, stale, hidden, cut by their container). The first audit failed 111 of 176 cells; now 0 at every size, 150 %, Black and White. Fixes: A (`6e1874b` row rings and touch sizes and the A–Z scrub, `85bb6be`, `3dc1e77`, `8276c64`, `d8d73d0`) and C (`a066d65`, `ac2a6af`, `5336f7b`, `6aa74ee`). No Game Mode perf regression. **Parity:** Linux OS accent and Windows handheld fullscreen (`2ab4de7`), `.tar.xz` (B `8bf99ac`), virtual pads uinput/ViGEm (C, `docs/VPAD_PLAN.md`; verified live on the Deck), and the keyboard seat verified in Game Mode on the Deck.
* **Discord (ADR 0022, `docs/DISCORD_PLAN.md`, C):** `kouch-discord` (run-time SDK load, one thread), sign-in in Settings › Accounts, Discord friends beside Steam's (Discord's official symbol on the avatar; no Steam logo on avatars per Valve's rules), rich presence and invites. Waiting on the owner's portal settings (Public Client, the `http://127.0.0.1/callback` redirect) and one sign-in (`cargo run -p kouch-lab -- discord-link`). The SDK isn't in release builds until Discord's redistribution terms are confirmed.
* **Brand and boot, 2026-09-28/29.**
  * **Logo:** the owner picked K3 after four concept rounds (canvas <https://claude.ai/artifact/A4wS7Kfb8aV4gYtDLredUm>, page "Logo: K3 (chosen)"). The SVGs are in `app/ui/src/assets/brand/kouch/` (`be3c6fc`, `2f4730d`, `333c416`); players 1–4 wear the logo's colours (`0546ac0`).
  * **Boot:** drop-in-and-sit with a landing pulse per seat (`b05bbb6`). The Steam path's haptics and rumble deadlines (`e90ef13`, C) and Boot's clock (`45b5283`) followed.
  * **Deck, Game Mode:** `boot_replay` \~61 fps (see the gotcha); every other phase unchanged.
  * **Steam store art** (K3) is in the owner's `Pictures\kouch-steam-assets\FINAL`, not in git.
  * **App icon (2026-09-29):** the couch mark alone on a transparent square, in exe, installer, taskbar and AppImage. `scripts/gen-app-icons.mjs` redraws every size natively from `kouch-mark.svg` into `app/src-tauri/icons/`: a real multi-size `.ico` (16–256) and PNGs up to 512. The sofa is white, so on a light taskbar only the four players show (a thin dark outline would fix that; not asked for).
* **Social, 2026-09-29 (C, owner feedback):**
  * **Done:** toasts wrap any text (`05eacfd`, A); image DMs toast as "sent an image" and the focus entry rule is fixed (`02f63c2`); DMs draw pictures, stickers and emoticons for Steam and Discord (`e1b4156`).
  * **Next:** recent DMs with previews at the top of the Friends widget (Steam and Discord), then animated avatars and avatar frames.
* **Motion in a real game under Steam, 2026-09-29 (B, owner at the PC; `docs/EARLY_TESTS.md` "Motion in a real game under Steam"):**
  * Pointing works with the owner's pad.
  * Steam caps acceleration at ±2 g per axis, so hard shakes arrive flattened. The pointer-console profile drives the emulator's own shake on the controller and its attachment when an axis nears the cap, or while R1 is held (`b5d0427`). Owner-confirmed.
  * Rumble can't come back over DSU. Routes: the emulator's own SDL, or Kouch's virtual pad. **Owner, 2026-09-29: the emulator's own SDL (no driver), only if it doesn't interfere with inputs** (the pad bound for rumble only, each player's own pad). B builds it; the virtual pad stays opt-in.
* **Goal round, 2026-09-29 (kouch central; owner: responsive, full keyboard + mouse, smooth, deep testing, motion in games):**
  * **Second PC** ("Airi", `I:\nextcloud\whatever\kouch-test`): rounds 1–6 of re-tests and four online rounds. Joins, lobby chat, invite cards (they keep their game after a restart), keyboard-only online play, Leave and the toast's hold all pass. Round 6 (b1058b7): 9 of 11 FIXED; the rest went to A and C.
  * **The Friends widget fits** at every size from 1280×720 to 4K and at 150 %: no whole row left empty (C, `ef060df`, `7ca4d51`).
  * **Keyboard and mouse:**
    * one key map (`lib/keymap.ts`);
    * Tab reading order;
    * `scripts/ui-crawl.mjs`;
    * a click keeps keycap prompts (`44c8b6d`);
    * sliders enter with A (`2d4a5c6`).
  * **Joining with A** no longer presses Home (C, `ca44c36`), and **R3 toggles a player's motion pointer** (C, `031b11a`). Both verified on the Deck with the dev vpad.
  * **Deck Game Mode, b1058b7:**
    * library views 84.8–89.8, home\_widgets 89–89.8, ambient 89.6;
    * home\_fold 83.3 (cause found: `composite: "add"`, see Gotchas; A fixing);
    * friends\_list 84.1 (a scroller layer gives 85.4; C);
    * connect \~82 (layout work per pad change; C);
    * the view-switch setup frame 60–105 ms (A's `#k-theme` fix cut playtime's from \~104 to \~65).
* **Steamworks SDK 1.65** vendored in `vendor/steamworks{,-sys}` via `[patch.crates-io]` (1.64 misreports the 2026 Steam Controller); see `vendor/README.md`.
* **GitHub Actions is out of budget** on the owner's account; `.github/workflows/ci.yml` is correct but does not run.


---

# 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/history.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.