Device checklist

Everything below needs a real Steam Deck (or SteamOS machine with Decky Loader) in Game Mode; none of it is a merge criterion for any plugin PR (spec section 4: "on device" acceptance items are transcribed here, not enforced by CI). Run it top to bottom the first time a build reaches a Deck. Findings that contradict the spec go to a Fable-class model (spec section 5), not decided here.

0. Setup

1. Get a build onto the Deck: curl -fsSL https://raw.githubusercontent.com/episode6/moonlight-steam-sync-decky/main/install.sh | sh (sudo prompts, explained by the script; without a password set it offers a temporary one, section 5). For a build newer than the latest release, build off-device with pnpm install && pnpm run build && backend/entrypoint.sh && python3 scripts/package.py, or take the Moonlight-Sync artifact from a CI run, and install it by hand — README.md's "Manual install". Either way Settings → About should show the bundled and installed CLI both at the plugin's version (the CLI is built from cli/ with it; 0.4.0 before the move); the plugin installs or upgrades ~/.local/bin/moonlight-steam-sync on first load.
2. SSH into the Deck while it sits in Game Mode (passwd once in Desktop Mode, then sudo systemctl enable --now sshd; see probes/PROBES.md §1.1 for the full one-time setup, which the PR-0 probes below also need).
3. Logs: ~/homebrew/logs/Moonlight Sync/moonlight-sync.log (every CLI call with its arguments, the CLI's own stderr verbatim, both CLI versions at startup) and Decky's own log (~/homebrew/logs/decky-loader/… or journalctl -u plugin_loader) for backend tracebacks. Settings → About also shows a log tail and both CLI versions without leaving the panel.
4. To flip the controller-layout strategy by hand (no UI yet, spec §3.10): stop the plugin (sudo systemctl stop plugin_loader or unload it from Decky's developer menu), edit "layout_strategy" in ~/homebrew/settings/Moonlight Sync/settings.json to "copy" or "picker" (removing the key restores the default, currently "copy"), then reload.
5. The CLI must work from the plugin, not only from SSH: plugin_loader is a PyInstaller binary whose LD_LIBRARY_PATH=/tmp/_MEI… once broke the CLI's flatpak call ("moonlight CLI not found") and its import ssl ("5 consecutive network failures"). With Moonlight installed as the Flathub flatpak, pick a host in the panel and search for a title in the match fixer; then grep -n "not found\|network failures" "$HOME/homebrew/logs/Moonlight Sync/moonlight-sync.log" must find nothing newer than the install. To reproduce the loader's environment from SSH, while plugin_loader is running (its unpack directory goes when it exits): env -i HOME=$HOME PATH=/usr/bin LD_LIBRARY_PATH=$(ls -dt /tmp/_MEI* | head -1) python3 ~/.local/bin/moonlight-steam-sync doctor — the moonlight: line must name the flatpak (CLI 0.3.1 or newer; 0.3.0 prints not found there, which the plugin's cleaned environment hides). ls -dt takes the newest _MEI* directory; if another PyInstaller program is running too, check that the one picked holds a libssl.so.3. The loader's own /proc/<pid>/environ is not the shortcut it looks like: the service runs as root, so reading it needs sudo, and even the backend's deck-owned process refuses.

1. PR-0: device probes

The primary path is the scripted runner; the throwaway steam-input-probe plugin is the fallback. Full procedure, venv setup and the exact commands: probes/PROBES.md. The fallback button plugin logs to ~/homebrew/logs/steam-input-probe/steam-input-probe.log (the loader's DECKY_PLUGIN_LOG_DIR; a loader old enough not to set it falls back to ~/homebrew/logs/steam-input-probe.log). In order:

• Setup (PROBES.md §1.1): SSH in, create the ~/.cache/msy-probes venv, confirm the CEF DevTools port answers (curl -s http://localhost:8080/json | grep -c SharedJSContext).
• V4: run_probes.py v4 — dump the first 20 of collectionStore.allAppsCollection.allApps (appid, display_name, app_type) and the current steamid3. Expect real entries and a plausible steamid3.
• V1: run_probes.py v1 --appids <owned appid>,<another> — dump GetConfigForAppAndController per appid plus the Deck controller index found by type. Expect a template:// or workshop:// URL for a game with a chosen layout, default://… for one left on Steam's guess, and the controller index (record it — it decides the DECK_CONTROLLER_TYPE fallback in src/lib/layouts.ts if it is not what the constant assumes).
• V2 (state-changing, needs --url; make a throwaway shortcut first): run_probes.py v2 --shortcut <APPID> --url 'workshop://…' (an id published for a real game you own) — calls SetSelectedConfigForApp then reads back. Expect the read-back URL to equal what was set. This decides the strategy: if it does not match, flip DEFAULT_LAYOUT_STRATEGY to "picker" in src/lib/layouts.ts and rewrite the README's "Controller layouts" section — escalate to a Fable-class model rather than doing this inline.
• V5: run_probes.py v5 --shortcut <APPID> [--run] — dump appStore.GetAppOverviewByAppID(appid).gameid and, with --run, launch it. Expect a non-null overview once Steam has loaded the shortcut list, and (with --run) the shortcut to actually launch.
• V3 (state-changing, needs --yes or an interactive confirm): run_probes.py v3 — logs pgrep -x steam every 100 ms for 90 s around a StartShutdown(false) call, then reconnects to confirm Steam came back. Expect the log to show a clear gap between the client going away and coming back, confirming StartShutdown(false) is the restart from Game Mode (spec §2.3). The measurement is gaps (from the pgrep samples), not back_after_ms: that field is measured from the start of the watch and the reconnect only begins after the baseline plus the whole --duration, so it is bounded below by roughly 91 s whatever Steam does. Read it only as "Steam came back: yes/no" (PROBES.md §1.3).
• Run run_probes.py all --appids … --shortcut <APPID> [--url … --yes] once everything above passes individually, and paste probe-results.json's --markdown table into ~/specs/moonlight-steam-sync/decky-plugin.md §2 (a Fable-class model does the actual spec edit).

2. PR-5: backend, Quick Access panel

• First load installs the bundled CLI. With no ~/.local/bin/moonlight-steam-sync present, load the plugin. Expect it to appear in ~/.local/bin after load, and Settings → About to show both the bundled and installed versions matching the plugin's own version (About's Plugin version): the CLI is built from cli/ at the same version.
• Counters, Sync now, the restart modal. Press Sync now. Expect progress lines, then either the restart modal (writes pending) or "nothing to do"; the four counters and Last sync update after. The progress bar and its "ARTWORK: TITLE N OF M" label stay inside the panel, the bar as wide as the Stop button under it (before 2026-09-23 the bar's fixed-width column overflowed the panel).
• Stop right after Sync. Press Sync now, then Stop within about a second (before the first progress line). Expect the panel to leave the progress view reporting a stopped run (not a run that keeps going), Last sync not claiming any added/replaced shortcuts, and ~/homebrew/logs/Moonlight Sync/moonlight-sync.log (or Decky's own log) to show either "stop: SIGINT to the sync run" or "stop: the sync run has not spawned yet; it will be interrupted", exit 130.
• Stop during the await-exit wait. Start a sync that has writes to make, wait for the "close Steam" state, press Stop, reopen the panel. Expect the persistent "Restart Steam to apply" row to still be offered (nothing was written) and Last sync not to claim any added/replaced titles.
• Unload during a run. Start a sync, then reload the plugin (Decky's developer menu → reload, or reinstall). Expect pgrep -af moonlight-steam-sync to return nothing a few seconds later, and a fresh Sync now afterwards to start exactly one run.
• Open Moonlight launches the client shortcut without picking a game.
• Desktop / Steam Big Picture show on the panel when the active host publishes them, each starts its stream with the controller layout chosen on that shortcut, and neither shows once its entry is ignored and synced away.
• Backend not answering at load. Force the failure (open the panel immediately at Game Mode start, or temporarily rename ~/homebrew/plugins/Moonlight Sync/py_modules to break a callable). Expect a Retry row carrying the backend's message instead of an endless "Loading your library…" spinner; restore, press Retry, expect the panel to fill in without a plugin reload.
• The host is never asked on its own (Decision 66). Open the panel, close it, reopen it, toggle the plugin off and on, open Settings → Titles: moonlight-sync.log shows no --json list --host without --cached for any of it, and (with several hosts) the host row reads a grey circle and "N apps" with Check and (when a MAC is known) Wake under it. A shut-down PC stays down through all of it.
• Check asks once. With several hosts, press Check: "Checking…", then a green circle and "N apps"; the log shows one live --json list --host. A second press within 10 s is answered from the memo (no new spawn). While a sync runs elsewhere (or the library is still loading) the whole Host row is dimmed, label and count included, and the dropdown does not open.
• Check with one host. With a single host, press Check: expect no "Checking…" text anywhere (there is no row to put it in), the Check button unavailable meanwhile, then Check / Wake gone when the host answered, or the red error line alone above them when it did not; one live --json list --host in the log.
• Unreachable host row. With several hosts and the active one unreachable, press Check: expect a red circle and the cached "N apps" in the Host row, and under the dropdown, above the divider, the CLI's error message and "last seen " in red. For a host never listed the row says "never synced" and the error line is the message alone; with one host the line ends "· never synced" instead. A Sync now that fails with exit 3 paints the row the same way, and one that lists paints it green and takes the error line away, with no check_host spawned for either.
• One host: no Host row. With a single host, expect no Host row and no dropdown: Check / Wake directly under Enable Sync until the host is known reachable, then Sync now first. An unreachable host shows the error line alone above Check / Wake. Check / Wake sit as far below the divider above them as Sync now does when they are gone, with a divider of their own under them. Add a second host on Settings → Host: the row and its dropdown appear; Forget it: they go again.
• The switcher takes the row's spare width. With several hosts, expect the dropdown to start right of "N apps", never over it, and show a host name of a dozen characters whole, not cut at half the row; a longer name ends in "…" rather than pushing the count under the dropdown. The dropdown opens, lists every host and switches as before (the row is a Field with childrenContainerWidth="max" around a Dropdown, not a DropdownItem; the count running under the dropdown was seen on a Deck 2026-09-29 and the fix measured there over the debugger).
• In-game guard. While a game is running, expect no restart countdown and the text "A game is running. Restart Steam when you're done."
• In-game guard on the persistent row (Decision 29). With a pending "Restart Steam to apply" row (either kind: a pending write, or artwork), launch a game and open the panel. Expect the row to be disabled with the subtitle "A game is running; exit it first", and pressing it to do nothing. Exit the game: expect the row to become pressable again. Also press the row just before launching a game so the re-run's awaiting-steam-exit lands while the game is up: expect the restart modal (with its in-game text) rather than Steam shutting down under the game.
• Later → the persistent row → immediate restart. Press Later on the restart modal, expect the "Restart Steam to apply" row; press it, expect the sync to re-run with immediate_restart: true and shut down at once on the next awaiting-steam-exit, no modal.
• Art-only restart (a run with only artwork filled, no shortcut writes) offers the same modal/row with "New artwork needs a Steam restart to show".
• Restart countdown slider. Settings → Advanced: expect the countdown to run 0-30 s and no further (Decision 30 — the CLI stops waiting for Steam after 60 s, so a longer countdown would race it). Set 0 and expect the modal to show buttons with no countdown; set 30 and expect it to count down from 30. A settings.json left over from an older build with "restart_countdown_s": 60 must read back as 30, not break the settings page.
• Re-fetch all art with no --commit support. Install (or hand-build) a CLI whose art --help lacks --commit. Expect Re-fetch all art to be disabled, and if pressed anyway from a stale state, the message to read "re-fetching art from Game Mode needs a CLI whose art command accepts --commit" — never "CLI too old (0.4.0, needs 0.4.0)".
• Nothing about the other hosts. Add three hosts (one active, two not), sync the inactive ones once each so they have cached listings. Expect the Host row to say nothing of them: the circle and the active host's count only, no "parked" line.
• The SteamGridDB key round-trip and Test. Set a key on the Artwork page, expect only its last four characters ever shown anywhere (panel, events, logs); press Test, expect a pass/fail result with no more of the key revealed.

3. PR-6: Titles page, Change match

• Titles list, idle. With nothing running, press the panel header's list button. Expect "N published by MY-GAMING-PC · sorted by name" and rows with capsules, badges and chips.
• Titles page mid-sync. Start Sync now, then open Settings → Titles while it runs. Expect "N published by MY-GAMING-PC[ · listed ] · refreshes when the sync finishes", the note "A sync is running; this list refreshes and matches can be changed when it finishes", and Change match disabled on every row.
• list --cached always, never live list (Decision 66). Whether or not a sync is running, opening Titles spawns only --json list --cached --host MY-GAMING-PC, never a live --json list --host MY-GAMING-PC; the log proves it.
• Refresh after the sync. Let it finish (restart when prompted), reopen Titles: it re-lists from the cache the sync just wrote, the headline returns to "N published by MY-GAMING-PC · listed just now · sorted by name", Change match is enabled again.
• Never-synced host. On a host that has never been synced, open Titles: "MY-GAMING-PC was never synced; Sync now lists its titles" and a Sync now button, no rows, filters or Retry. Add OFFICE-PC and press Check on it (both cache its list), make it active and open Titles: the same line, still no rows. Press the page's Sync now: the line reads "… this list fills in when the sync finishes", the button goes, and the titles fill in after the run ends.
• Change match races a sync. Open Change match on a title; before pressing Use this, start a sync from the panel; then press Use this. Expect "A sync is already running", no pin written (matches.json unchanged), the row keeps its old match.
• Pin, then apply on next sync. After that sync finishes, press Use this again on the same title: expect a pin, the toast "Pinned; sync to apply", the pinned and "art refreshes on next sync" chips, and the next Sync now to turn an owned-game pin into a Stream button (Hades II re-matched from a fuzzy Hades hit is the spec's own example: expect a Stream button on Hades II and the visible tile gone).
• Ignore. Ignore on a title removes its tile on the next sync; Unignore restores it.
• Owned-apps mismatch recovery. Sign in as a second Steam user on the Deck, open Titles: expect exactly one write_owned_apps in the log (recovered once), then a successful list and status — not two write attempts.
• Paging. With 300+ rows, page through with the D-pad; expect pages of 50 and correct navigation at both ends.
• Recently added. After updating to a build with the chip, open Titles: the order is by name and added.json in the settings directory lists every title with null (no Moonlight, Desktop or Steam Big Picture in it). Publish a new app on the host, Sync now, restart when prompted, reopen Titles and press Recently added: the chip lights, the headline ends "sorted by recently added", the new title is the first row and reads "added today h:MM AM/PM" (or "HH:MM" with Steam's 24-hour clock on), every other row follows by name with no "added" text, and added.json has a time for the new title alone. Pick a filter: the order holds. Leave the page and reopen it: still newest first. Press the chip again: by name, no "added" text. With the chip on, start a sync and reopen Titles: the headline ends "refreshes when the sync finishes · sorted by recently added".
• The clock follows Steam's. With Steam's Settings → System → 24-hour clock off (measured on the Deck 2026-09-29: the toggle writes settingsStore.friendSettings.b24HourClock, which the header clock reads too), the Titles page's "added today 2:02 PM" and the panel's Last sync use the 12-hour clock; turn it on and reopen them: "added today 14:02", "Today 14:02 · …", with no plugin reload.
• No layout text on the rows. No Titles row says layout: …; the note beside a game's Stream button still does while a default is set.
• Show more keeps your place. Press Show 50 more with the D-pad. Expect focus on the last row that was already shown (not on the button, now 50 rows further down), and one press of down to land on the first new row.

4. PR-7: Stream button and controller layouts

The layout items in this section were written for the copy from the real Steam game, which spec 3.16 (§8 below) replaced with a default layout you adopt: nothing copies from the real game any more, there is no Advanced toggle, and the Titles rows have no layout button any more (Decision 75: a title's layout is picked from Steam's controller settings while it streams). Run the button, guard, route-patch, picker-strategy and controller-index items here as written; the copy-specific ones are marked and superseded by §8.

• Button placement. With a host active and a sync done, open the library page of an owned game the host publishes: expect a Stream row. Open a game the host does not publish (or one parked / matched to nothing): expect no Stream row.
• Focus order beside another plugin. With ProtonDB Badges (or any plugin that adds to the game page) installed, open such a page and press up from Play: expect the Stream button first and the other plugin's badge after it, as they are drawn, and the same order in reverse going down.
• First press copies a community layout. Superseded by §8 (nothing copies from the real game any more). With no default layout set, press Stream on a game whose real entry has a workshop:// layout: expect the launch with no layout change and no layouts.json write.
• A hand-picked layout on the hidden entry is never overwritten. Pick a layout on the hidden shortcut (Steam's controller settings while it streams), set a different default layout (§8), press Stream, then Sync now and restart when prompted. Expect the hidden shortcut to keep the hand-picked layout after all three, layouts.json to read "kept" with that URL and "applied": null, the game page's Stream note to read "own layout".
• Steam default. Superseded by §8: with a default set, a hidden shortcut on Steam's default gets the default layout on its first press ("default"); without one, nothing is written.
• One row, however often the page is opened. Open the same owned game's library page several times, backing out to the library and in again between each (and switch to another game's page and back). Expect exactly one Stream row every time — never two stacked — and no slowdown building up as the page is re-entered. The route patch runs afterPatch on each render, so a duplicated or accumulating row shows up here and nowhere else.
• No running-app guard. Launch any game, then open another published game's library page and press Stream: expect no toast and the Stream shortcut launched as usual (Steam switches to it; with a stream already going, Moonlight's own UI takes over), the default layout applied and layouts.json updated as on any press.
• Advanced toggle. Removed: the toggle is gone (spec Decision 47). Settings → Advanced shows Default controller layout instead (§8); "no default set" is the off switch.
• Post-restart layout walk. With a default layout set (§8), make a sync write shortcuts, restart when prompted, wait up to 90 s after Steam is back. Expect layouts.json to gain an entry per non-parked entry (default / kept / unavailable), the log to show the walk starting, each target, and "layout walk done"; the panel to show no restart row afterward.
• A title's layout while it streams. Press Stream on a game, then the Steam button: Controller settings there must be the hidden shortcut's (its title matching the game), and a layout picked there must still be selected at the next stream. The Titles rows have no Layout button (Decision 75); Advanced's Layout is §15's.
• Picker strategy. Set "layout_strategy": "picker" in settings.json (§0.4 above) and reload. Expect a Stream press to launch with no layout change and no layouts.json write, the Advanced Default controller layout field to read "Off for this device…" with Layout as its only button (no Make default, no Clear) and the plugin's only layout action, and no walk after a sync's restart; remove the key and reload to return to copy.
• Controller index by type. In the CEF console (or the PR-0 kit) with a Bluetooth pad also paired, run ControllerStore.GetControllers().map(c => [c.nControllerIndex, c.eControllerType, ControllerStore.GetControllerTypeString?.(c.eControllerType)]) (the global is ControllerStore, capital C, on the client probed on 2026-09-20; the list is empty while no controller is connected). Expect the built-in controller not at index 0 when the pad connected first, its type string "controller_steamcontroller_neptune", and eControllerType 4; if not 4, correct DECK_CONTROLLER_TYPE in src/lib/layouts.ts. Still open: the first probe device was a SteamOS box with a separate Steam Controller (index 0, type 10, "controller_steamcontroller_triton"), so this has not been seen on a Deck.

5. PR-8: this checklist and install.sh

• install.sh on a Deck: run the one-liner from a clean Deck (no plugin installed yet), with a password set for the deck user (the next item is the Deck without one). Expect sudo to ask for it (unzip into ~/homebrew/plugins/, restart plugin_loader), then Moonlight Sync appears in the Quick Access menu's Decky tab, and a final line naming the version that actually landed (read from the installed package.json, not the tag asked for). Re-run it; expect it to succeed again (reinstall/overwrite) without asking anything unexpected.
• install.sh on a Deck with no password. On a Deck whose deck user has none (passwd -S deck says NP; sudo passwd -d deck gets a Deck that has one back there), run the one-liner. Expect the question Set a temporary password for the install? naming Decky!. Answer n: expect exit 1, "nothing was installed", passwd -S deck still NP and no plugin directory. Run it again and answer y: expect no sudo prompt at all, no New password: prompt and no pause after the answer, the install and the restart, Removed the temporary password before the final line, and passwd -S deck back at NP afterwards. Run it once more, answer y and press Ctrl+C as soon as it says Temporary password set: expect passwd -S deck at NP again. Unmeasured until this is walked: that SteamOS's passwd takes the new password from a pipe (run under setsid, so with no terminal to ask on) and that passwd -S answers for one's own account without root (both are what Decky's installer relies on). Should the pipe not be read, the script says sudo did not accept the temporary one and installs nothing.
• install.sh on a device without Decky Loader. On a device that has none (no ~/homebrew/services/PluginLoader), run the one-liner. Expect Decky Loader is not installed and the question Install Decky Loader now? before anything is downloaded. Answer n: expect exit 1, "nothing was installed", no sudo prompt and no ~/homebrew. Run it again and answer y: expect Decky's own installer's output (Installing Steam Deck Plugin Loader release...), Decky Loader is installed., then the plugin's install as in the items above (on a Deck with no password, the temporary-password question comes between the two downloads and Decky's installer), and at the end the two lines saying the Decky tab appears once Steam has restarted. Return to Gaming Mode: expect the Decky tab with Moonlight Sync in it. Run the one-liner once more: expect no question about Decky Loader. Unmeasured until this is walked: that Decky's install_release.sh runs to the end as sudo bash <file> with stdin from /dev/null (it is documented as curl … | sh, where it re-executes itself under sudo), and that a return to Gaming Mode is enough for the tab to appear.
• The README's manual install. With the plugin not installed, follow README "Manual install": Decky's settings → General → Developer mode on, then Developer → Install Plugin from ZIP File → Browse, choose a release's Moonlight-Sync.zip, confirm Decky's dialog. Expect Moonlight Sync in the Decky tab with no restart, and Settings → About showing that release. Do it again over the installed copy: expect Decky to ask to reinstall or overwrite, and the plugin to reload. Unmeasured until this is walked: the labels as the README spells them.
• A missing release is explained. Run with MOONLIGHT_SYNC_VERSION=v9.9.9; expect install.sh: could not download …/Moonlight-Sync.zip (is v9.9.9 released?) on stderr, exit 1 and nothing written to ~/homebrew/plugins/.
• MOONLIGHT_SYNC_VERSION pinning. Run with MOONLIGHT_SYNC_VERSION=v0.1.0 sh install.sh (or the exact tag); expect the version-specific download path, not latest/download.
• Uninstall. Follow the README's "Uninstall" section (sudo rm -rf ~/homebrew/plugins/"Moonlight Sync" + restart plugin_loader); expect the Quick Access entry to disappear and ~/.local/bin/moonlight-steam-sync (the CLI) to be untouched.

6. Host apps: the panel buttons replace the tiles (spec 3.14)

Needs a host that publishes Desktop and Steam Big Picture under those names, and ideally an install from before this change: two visible tiles, one of them with a controller layout chosen on it. Note each tile's appid first (moonlight-steam-sync --json status).

• The first sync hides the two tiles in place. Upgrade the plugin, press Sync now. Expect the plan to count them as hidden, never as replaced (the log's CLI line says N to hide; no replace event for either name), one Steam restart, and afterwards no Desktop / Steam Big Picture tile anywhere in the library, non-Steam collection included.
• Same appid, nothing lost. --json status --hide-host-apps shows both entries with the appids noted above, hidden: true, parked: false, host_app: true, and their artwork slots still filled; no image was downloaded for them by that sync.
• Both panel buttons launch. Desktop and Steam Big Picture each start their stream from the Quick Access panel; Recent Games and the in-game overlay show the entry with its artwork.
• Each layout button opens the configurator. Removed: the panel has no layout button per host app any more (spec Decision 67), nor on the Titles page (Decision 75); a host app's layout is picked from Steam's controller settings while it streams, and the one Layout button, Advanced's since Decision 77, is the Moonlight entry's (§15).
• A layout chosen before the upgrade is still selected (same appid): it applies in the stream, and Steam's controller settings during the stream show it.
• While a game runs the two launch buttons still work: a press runs the host app's shortcut as usual.
• On a client without SteamClient.Apps.ShowControllerConfigurator (if one turns up) Advanced's Default controller layout row has Make default and Clear only.
• Counters. Do this one before the first sync: status carries the flag from the upgrade on, so the two still-visible tiles already read host_app: true. Right after the upgrade Shortcuts is two lower than before (and Unmatched lower by however many of the two had no match); Stream buttons is unchanged. The sync that hides the two then moves none of the three.
• Titles page. Both rows read host app, show under All only, and have Change match and Ignore (no Layout, as on every row). In Change match every result reads art only, including a game this account owns; pin one, sync, and expect the entry to stay a hidden host app with new artwork and no Stream button on that game's library page.
• No layout copied onto them. (Written for the layout copy that spec 3.16 replaced; §8 covers them now.) Without a default layout set, after a sync's restart the layout walk never touches the two entries (layouts.json has no copied / kept / unavailable record for their appids; a picker record from an older version's Choose layout… may stay). With a default set they get it, like every other entry (§8).
• Ignore removes the button. Ignore Desktop on the Titles page and sync: the entry is removed and the panel's Desktop row is gone. Unignore and sync: it comes back, hidden from the start.
• Switching hosts. With a second host that does not publish them, the two entries are parked (counted under parked, buttons gone); back on the first host they are unparked hidden, never as tiles.
• Getting the tiles back (README, "The Quick Access panel"): the full command there (--owned-apps, --ignore-file, --client-shortcut, --park-unpublished, no --hide-host-apps), run from a terminal, shows the two tiles again with art and layout intact and changes nothing else: every Stream button stays hidden, no ignored title comes back, the Moonlight client entry stays. The next Sync now hides the two again.

7. Hidden shortcuts and the Streaming collection (spec 3.15)

None of collectionStore.SetAppsAsHidden, BIsHidden, userCollections, NewUnsavedCollection, AsDragDropCollection or a collection's Save / Delete was probed before this was built; every item here is a first measurement. Spec 3.17 changed the collection items below: the collection now exists only with Hide Stream shortcuts off, beside the tab, and holds shortcuts only; §10 has the items that replace the collection ones here, and the hiding items still stand.

• In the CEF console: typeof collectionStore.SetAppsAsHidden, typeof collectionStore.BIsHidden, typeof collectionStore.NewUnsavedCollection are all "function", and Settings → Advanced shows both toggles enabled (a disabled toggle says the client has no such call).
• After the plugin loads with an existing install: the Non-Steam tab holds only the visible shortcuts (the panel's Shortcuts counter), no Stream-button shortcut, no Moonlight, no Desktop / Steam Big Picture, no parked title. They are all under Steam's Hidden.
• A Streaming collection exists and its size is the panel's Stream buttons + Shortcuts. An owned game in it opens the real game's page (with the Stream button); an unowned one is the shortcut.
• A Stream press still launches the (now hidden) shortcut, and the panel's Open Moonlight, Desktop and Steam Big Picture still work.
• Hide Stream shortcuts off: the Stream-button shortcuts appear under Non-Steam within a moment, the other hidden entries do not, and the collection is unchanged. Stream a game, quit: its shortcut is at the front of Home. On again: they are gone again.
• Streaming collection off: the collection is deleted. On: it is back, complete.
• Sync after the host gains a title: once Steam has restarted, the new Stream shortcut is hidden and the game is in the collection without opening the panel (allow 90 s). Note whether the tile is visible for a moment first.
• Switch hosts and sync: the first host's visible tiles are hidden (parked) and leave the collection; switching back shows them again.
• Remove everything: after the restart the collection is gone and Steam's Hidden holds none of the plugin's entries.
• After a host switch (or an Ignore + sync) that removes a visible shortcut: the collection's allApps no longer lists its appid (the plugin cannot remove a member whose overview is gone, so the client has to drop it itself).
• The first sync on a fresh install creates the collection with every member in it (the port saves a new collection empty, then adds).
• Open the panel and the Titles page a few times: nothing in the library flickers and collectionStore is not written again (the reconcile only applies differences).

8. The default controller layout (spec 3.16)

The plugin never reads the real game's layout any more: one layout you adopt from the Moonlight entry with Advanced's Make default (the one place since Decision 74: the Titles rows and the library gear menu no longer offer it, and since Decision 77 the panel does not either) is put on every entry the plugin manages, and a selection the plugin did not make is never overwritten (applied in layouts.json is what the plugin last set per shortcut). Two things here are unmeasured on any device: whether a template:// layout sticks on other titles, and the name and arguments of the call that clears a selection (SteamClient.Input.ClearSelectedConfigForApp(appid, controllerIndex), spec 3.16.3 [verify]). Do this section with a controller connected; Make default answers "Connect a controller first" otherwise.

• Adopt a community layout. Give the Moonlight entry a workshop:// community layout (Advanced's Layout), then press Make default beside it. Expect a confirm titled Use “<layout title>” as the default layout?; after OK, a toast Default layout applied to N titles (N = every non-parked entry that had no layout of its own, host apps and the Moonlight entry included) plus · M kept their own for the ones that had; Settings → Advanced → Default controller layout reading <title> · Workshop layout · set today …; layouts.json with "default" and "applied" set to the URL for each. A fresh title (a game the host just started publishing, after its sync and restart) streams on it without any press first.
• No other place adopts. The Titles rows have no Layout button (Decision 75), a streamed game's gear menu has no Use as Moonlight Sync default layout (Decision 74), and the Quick Access panel has no layout row (Decision 77).
• Adopt a template:// layout [verify]. Pick one of Steam's own templates on the Moonlight entry, adopt it. Expect the same toast; check layouts.json: every other entry must read "default" with the template:// URL. If they read "unavailable" instead (the URL did not stick when read back), report it: template:// then has to come out of DEFAULT_LAYOUT_SCHEMES (spec 3.16.1, Decision 49), a Fable-class decision.
• An edited-in-place layout is refused. Edit the Moonlight entry's layout in Steam's layout screen without exporting it (it reads autosave:///…), then Make default. Expect only the toast This layout was edited in place and only exists for “Moonlight”. In Steam's layout screen choose Export, select the exported copy, then try again., no confirm, no change.
• An exported personal layout works. Export that layout, select the exported copy on the Moonlight entry (it now reads workshop://…), adopt it: expect the normal confirm and toast.
• No layout is refused. With the Moonlight entry never given a layout (reads default://…, or a template:// Steam only offers), expect the toast “Moonlight” has no layout chosen yet. Use Layout first. (§15 has the same item.)
• Hand-picked survives, plugin-applied moves. With a default set, pick a different layout by hand on one title (Steam's controller settings while it streams), then give the Moonlight entry another layout and adopt it as a second default. Expect the hand-picked title unchanged ("kept", "applied": null, Stream note "own layout"), every plugin-applied title on the new default, the Moonlight entry (the source) unchanged, and the toast's M kept their own counting the hand-picked one and the source.
• A pre-upgrade copied title moves. On an install upgraded from a version that copied layouts from the real game (layouts.json has "copied" records without an "applied" key), set a default: expect those titles to move to it (Decision 46) as long as their selection is still the copied URL.
• Clear [verify]. Settings → Advanced → Clear: expect the confirm Clear the default layout?, then the toast Default layout cleared · removed from N titles. Every plugin-applied title must be back on Steam's default (the layout screen shows nothing selected; the row reads "Steam default", "applied": null), and hand-picked ones must keep their layout. In the CEF console first check typeof SteamClient.Input.ClearSelectedConfigForApp: if it is not "function", the toast reads Default layout cleared. This Steam client cannot unset a layout, so titles keep the one they have. and nothing changes on any title; if it is a function but titles are not back on Steam's default afterwards ("unavailable" with the old URL in layouts.json), the call's name or arguments are wrong: report it (spec 3.16.3), do not guess at another.
• A sync's new titles get it after the restart. With a default set, add a title on the host, Sync now, restart: within 90 s the new shortcut is on the default (layouts.json, and the layout screen).
• The host apps, the client entry and a visible shortcut get it. After any of the above, check layouts.json for Desktop, Steam Big Picture, Moonlight and a visible (non-Stream) shortcut: "default" with "real_appid": null for the first three.
• Not held back. Start a game, then adopt a default from the panel or clear it from Advanced: it goes through (the toast appears) while the game runs; a Stream press is still refused meanwhile.

9. Fixtures vs. real CLI

• Run, on the device, against the real installed CLI: moonlight-steam-sync --json list --hide-host-apps, --json status --hide-host-apps (the plugin always passes that flag, and the fixtures carry its keys: kind: "host-app", entry.host_app), --json host show, --json search "Portal". Diff each event's key set against the corresponding fixture under tests/fixtures/common/ (§3.6.3 of the spec: tests/test_fixtures.py checks the fixtures against the schema, but never against a real CLI run). A mismatch means the CLI and the plugin have drifted from the spec's §3.4.6 schema on one side or the other — escalate to a Fable-class model rather than editing either side ad hoc.

10. The Streaming tab (spec 3.17)

The /library route's render tree was measured on 2026-09-22 through the CEF debugger (route element → the library home, which reads the route's tab id → the library page, tab prop, which builds its tab array in a useMemo and validates the requested id against it in its own render → the tabbed page {tabs, activeTab, onShowTab, …} behind an observer wrapper → the tab row, which renders and cycles over tabs; a built-in tab is {id, title, renderTabAddon, content, footer}). The patch still digs for the tab bar's tabs array (four component levels at most) so a client that adds a level keeps working, and clones a built-in tab's grid element with a synthetic collection whose surface is a guess at the client's Collection. The items after the first two are still first measurements.

• With an install that has synced: the library's tab bar has a Streaming tab after Non-Steam, and it opens. If there is no tab, note the CEF console: Moonlight Sync: could not patch the library tabs names a throw; silence means the walk never found a tabs array (report the route element's shape: typeof route.children.type, whether props.renderFunc exists).
• The tab can be reached: L1/R1 from Non-Steam lands on it, and moving along the tab row with the D-pad stops on it. Found 2026-09-22: both asked the library for it (onShowTab navigates to /library/tab/MoonlightSyncStreaming), and the page answered with its first tab, since it validates the id against its own tab array in its render, before the injection; activeTabFor puts the id back on the bar element. If it is skipped again, report from the CEF console the one Moonlight Sync: library tabs found on … line (the bar's prop names, activeTab, a built-in tab's keys, the template's type and prop names) and whether a Moonlight Sync: library tabs, onShowTab("MoonlightSyncStreaming") line appears when you try: none means the bar never asked for it; one that does not open it means the page's tab prop is no longer the requested id (requestedTab in libraryTabs.tsx).
• The tab's own panels take focus: with no host, or before a sync, the No host yet / Nothing to stream line gets the focus ring. They are a Focusable with focusableIfNoChildren and a no-op onActivate (both unmeasured); Settings → About's log panel is a plain Focusable over text, so whether it takes focus says whether a plain one already suffices.
• The tab's tiles are the panel's Stream buttons + Shortcuts: an owned game opens the real game's page (with the Stream button), an unowned one is the shortcut. Sorting, the footer legend and the focus ring behave like Non-Steam's. A blank tab, or a line that starts Moonlight Sync could not draw this tab on this client (the plugin's own error boundary; the console has the same error with its component stack), means the grid read something the synthetic collection lacks: report the console error, do not guess at the field.
• Steam's own tabs are unchanged, and Settings → Moonlight Sync's tab bar has no Streaming tab (the injection only takes a tab bar some tab of which renders a collection).
• Nothing remounts: switching between library tabs and back does not flash or reload the grid (each patched component type is cached).
• The tab is not a collection: Collections has no Streaming entry, and on a second machine signed into the account nothing appears.
• Upgrade from v0.4.0: the old Streaming collection loses this device's owned games and shortcuts at the first load and is gone once empty; a member the plugin never made (add one by hand first) stays, and so does the collection.
• After a sync that adds or removes a title, the tab follows without reopening the library (its content reads the store).
• Hide Stream shortcuts off: the Streaming tab stays (its tiles unchanged) and a Streaming collection appears within a moment with the Stream shortcuts and the visible shortcuts, no owned game. On again: the collection and its shortcuts stay (hidden, so the collection looks empty in the library), and the tab is untouched.
• Streaming tab off: the tab is gone (leave the library and come back) and this device's shortcuts leave the collection, parked ones too (deleted once empty). On: both back.
• The first sync with the collection in effect on a fresh install creates it with every member in it: whether the client lists a just-added member at once is unmeasured, so the reconcile never deletes on the pass that added; if the collection is there but empty after that pass, the next reconcile (open the Titles page) must not delete it.
• Switch hosts and sync: the tab shows the new host's titles only.
• Remove everything: after the restart the tab reads "Nothing to stream from … yet" and, with the collection in effect, the collection is gone once the client has dropped the removed shortcuts.
• Unload the plugin (Decky → the plugin's menu → Uninstall, or a reload): leave the library and come back: the tab is gone, and the library still works if it had been the active tab.

11. Wake-on-LAN (spec 3.18)

The MAC source and the packet were tested off-device against a hand-written Moonlight.conf and a recording socket (tests/test_wake.py); the Deck's own file, the network and the PC's firmware are what these check. Two things ran on the SteamOS box on 2026-09-23: its Moonlight.conf carried the MAC as a quoted @ByteArray (a raw byte of the MAC was a comma), which the parser then read as unknown (fixed, with that line's shape as a test); and a packet capture on the same LAN showed Moonlight's own list sending a magic packet with the PC's MAC, which is what Decision 66 answers.

• Moonlight's MAC is read. With the host paired in the Flathub Moonlight, the panel's host row shows Wake beside Check while the host is not known reachable. If there is no Wake, open ~/.var/app/com.moonlight_stream.Moonlight/config/Moonlight Game Streaming Project/Moonlight.conf and note the host's mac= line: @ByteArray() (quoted or not) means Moonlight has none (a Sunshine host that reports no MAC; there is no field to enter one since 2026-09-26); anything else that still gives no Wake is a parser gap: paste the line's shape (hex masked) into an issue.
• Wake appears and sends. Shut the PC down (a sleep state Wake-on-LAN is enabled for). Open the panel: Check and Wake are side by side, under the host row's cached count when there are several hosts (the PC stays down: nothing was asked). Press Wake: a toast "Wake-on-LAN packet sent to . Give it a minute, then Check." and, in moonlight-sync.log, wake_host <host>: N packets sent (moonlight MAC) with N = (1 + the host's addresses) × 8. The PC wakes; Check after a minute goes green.
• Check wakes it too. Shut the PC down again; press Check instead: Moonlight's own list sends the packet, so the row goes red first (the 30 s seek times out) and the PC comes up anyway; Check again after a minute goes green.
• No MAC in Moonlight: the row shows Check alone, and Settings → Host has no MAC field (removed 2026-09-26). A wake_macs key left in settings.json by an older build changes nothing: no Wake, no (settings MAC) in the log.

12. The on/off toggle (spec 3.19)

Off-device the controller is covered (controller.test.ts, "the on/off toggle"); what the client does with a hidden visible shortcut, the tab removed from a bar it was in, and a Stream row on a page already open are what these check. Start with the plugin on, synced, with Hide Stream shortcuts off (so there are visible shortcuts and a Streaming collection to watch).

• Off hides everything. Panel → Enable Sync off. The panel shows the toggle alone. In the library: no Moonlight shortcut under Non-Steam (the visible ones and the "Moonlight" client entry are gone too), no Streaming tab in the bar, and the Streaming collection is gone (or holds only entries another device put there). An owned game's page has no Stream row. A page that was open when the toggle flipped loses its row on the next render (open another game and come back).
• Settings are locked. The panel's header buttons and Settings open a route with the toggle alone: no Host / Artwork / Titles / Advanced / Updates / About.
• A reboot keeps it off. Restart Steam: the panel opens on the toggle alone and the library is still clean (the load's reconcile hides every entry again; the log has no check_host).
• On restores. Toggle on: the shortcuts are back where the settings put them (Stream entries hidden or shown per Hide Stream shortcuts, the client and host apps hidden), the Streaming tab and collection are back, the Stream row and the menu item are back, the host row goes green or red. If a sync's restart happened just before the toggle went off, the layout toast fires now.
• Busy. Start a sync, open the panel while it runs: the progress view has no toggle; when it ends the toggle is live again.

13. Reset match cache (Advanced)

Off-device the backend (test_backend.py, the reset_match_cache block) and the controller (controller.test.ts, "Advanced → Reset match cache") are covered; what a real cache and a real CLI do with the reset is what these check. Start synced, with at least one pin (Titles → Change match) and one title reading "no match".

• The file goes, and the toast counts it. Note ~/.cache/moonlight-steam-sync/matches.json (over SSH: the titles count and how many are "how": "pinned"). Settings → Advanced → Reset match cache → Reset in the confirm. The toast says "Match cache reset: N titles forgotten, M pins included…" with those numbers, the file is gone, hosts/ beside it is not, and the log has a reset match cache: deleted … line. Nothing changes in the library.
• A second press is harmless. The toast says the cache was already empty; the log says no file at.
• The next sync re-matches. Sync now: the CLI resolves every title again (the progress shows lookups, not cached hits), the titles that read "no match" get a match where SteamGridDB has one, the pinned title comes back as whatever the CLI resolves for it (the pin is gone) and titles that already had artwork keep it. The Titles page, opened after the run, agrees.
• Busy. Start a sync, open Advanced while it runs: Reset is disabled. Pin a title and press Reset within the moment the pin is saving, if you can: the toast says "A match change is still being saved" and the file is untouched.
• Off. With the plugin toggled off the Advanced page is not reachable (§12); nothing to press.

14. The SteamGridDB key from the Game Mode browser (spec 3.20)

Off-device the backend (test_cdp.py, test_sgdbpage.py over the fixture pages, test_hard_rules.py for the key in no event or log line) and the frontend flow (controller.test.ts, "the SteamGridDB key from the Game Mode browser"; the button's presence per key source in state.test.ts) are covered; the real pages, the real browser and the two navigation calls are what these check. The spec calls this section §13; that number went to Reset match cache first. Any selector of spec §3.20.1 that does not match on the Deck goes to a Fable-class model (spec §5), never loosened here.

Start with no key (Settings → Artwork → Remove if the key file is set; config.toml without [steamgriddb].api_key and no SGDB_API_KEY in plugin_loader's environment), and keep an SSH session tailing ~/homebrew/logs/Moonlight Sync/moonlight-sync.log.

• The button is where it should be. Settings → Artwork shows Get key from SteamGridDB… under the key field with no key, and again under Test / Remove once the key file is set. Put a key in config.toml (or SGDB_API_KEY in the service's environment), reopen the page: no button.
• The consent text. The button opens "Sign in to SteamGridDB with Steam?" with spec §3.20.4's text word for word, Continue and Cancel. Cancel does nothing else (no browser, nothing in the log).
• End to end, signed in to Steam. Continue: the Game Mode browser takes the screen on SteamGridDB, then Steam's Sign In page, then the API page, with no press of yours. [verify] NavigateToExternalWeb opens the same page target spec §3.20.1 item 2 measured (over the debugger, /json/list shows Preferences - SteamGridDB / …/profile/preferences/api); if it opens anything else, report it (the fallback is steam://openurl/ through SteamClient.URL.ExecuteSteamURL, and choosing it is a spec change). At the end [verify] NavigateBack leaves the browser and lands on Settings → Artwork; if the browser stays, note it here (it is left open by design then). The toasts are "SteamGridDB key saved (…XXXX)" with the key's last four characters, then "SteamGridDB accepted the key". The field reads "set, ends in …XXXX", and ~/.config/moonlight-steam-sync/sgdb-api-key is mode 0600.
• The field follows the fetch. While it runs, back out of the browser (B) to Settings → Artwork: the field says Waiting for SteamGridDB… / Signing in with Steam… / Steam is asking you to log in on the page / Reading your key… as it goes, and Cancel stands where Save was.
• Not signed in to Steam's web session. On a Steam account whose community session is gone (sign out of steamcommunity.com in the browser first), Steam's page asks for a password or a Steam Guard code: the field says Steam is asking you to log in on the page, nothing is typed for you, and once you have logged in the plugin presses Sign In once and carries on.
• An account with no key. [verify] (Decision 61) On a SteamGridDB account that never generated a key, the API page's Generate button is pressed once and the key is read after it; on a page with any key element, or only Regenerate / Revoke, nothing is pressed and the toast says "SteamGridDB shows no API key; generate one on its API page, then try again". Revoke API Key is never pressed in any run (the key you had still works: Test).
• A second attempt after a failure, no Steam restart. Make a fetch fail (the Left behind, then timed out item below, or Cancel mid-way), then press Get key from SteamGridDB… again: it succeeds. The log shows "sgdb key fetch: reset the browser's tab (was on www.steamgriddb.com)" (or steamcommunity.com) right before "started" (Decision 70), then waiting and the fresh page; never "failed (sgdb-page): no key and no generate button" within a second of "started". A device's 2026-09-25 had exactly that until Steam was restarted. Should the log say "could not reset the browser's tab", report it with the rest of the line: the fetch then reads the old page for its first polls (Decision 69) and should still succeed.
• Cancel mid-way. Start again, back out of the browser while Steam's sign-in page is up, press Cancel: within a second the toast says "The key fetch was cancelled", you stay on Settings → Artwork (no navigation back from there), the key file is unchanged, and the browser page is left where it was.
• Left behind, then timed out. Start again, back out of the browser with B and wait three minutes: the toast says "Timed out waiting for the SteamGridDB page; enter the key by hand or try again". Note where NavigateBack took you (it runs on every done of a fetch the plugin opened and was not cancelled from the page); if it left a page you did not expect, report it.
• No debugger. With ~/.steam/steam/.cef-enable-remote-debugging removed and Steam restarted (put it back afterwards; Decky recreates it), Continue toasts "Steam's debugger port is not reachable; enter the key by hand" and no browser opens.
• The key is never in the log. After the runs above, grep -c your key in ~/homebrew/logs/Moonlight Sync/moonlight-sync.log (and in Decky's own log, journalctl -u plugin_loader) is 0; the log has sgdb key fetch: <state> lines and "sgdb key fetched from the browser", never the key.
• Off. With the plugin toggled off the Artwork page is not reachable (§12); nothing to press.

15. The panel's launch row and Advanced's layout buttons (spec Decisions 67 and 77)

The panel's launch buttons are icons on one line; the Moonlight entry's Layout and Make default are in Settings → Advanced, beside Clear. Needs a synced host that publishes Desktop and Steam Big Picture.

• The toggle. The top row reads Enable Sync with no text under it, on or off. Settings, opened while off, shows the same toggle with the "Off: every Moonlight shortcut is hidden…" line under it.
• Sync now has no text under it.
• One launch row. The moon, the monitor and the Steam logo share one row, in that order, equal widths, nothing clipped or overflowing the 268 px column. The moon opens Moonlight; the monitor streams Desktop; the Steam logo streams Steam Big Picture.
• The caption follows focus. [verify] (onGamepadFocus on a DialogButton, unmeasured) D-pad onto each icon: the line under the row changes to "Open Moonlight · Launch the client…", "Desktop · Stream the host's desktop", "Steam Big Picture · Stream the host's Steam in Big Picture", and the footer's A legend names the same button. D-pad down off the row: the line goes back to Open Moonlight's (onGamepadBlur). If the line never changes, report it (the icons are then unlabelled on the Deck).
• A host app the host does not publish. Ignore Desktop on the Titles page and sync: the monitor goes and the other two icons widen.
• No layout row on the panel. Under the launch row come the counters; there is no Layout / Make default row.
• One layout row in Advanced. Settings → Advanced → Default controller layout has Layout, Make default and Clear on one line, right of its text, nothing clipped; the D-pad moves across the three and down to Hide Stream shortcuts.
• Layout. Layout opens Steam's controller configurator for the Moonlight entry; B comes back to Advanced. Pick a layout there.
• Make default. Make default asks "Use “” as the default layout?"; confirm, and the toast counts the titles that took it. The row's text now reads " · · set today …" and Clear is enabled. A Stream press on another game puts that layout on its shortcut.
• Make default with nothing chosen. On a Moonlight entry whose layout was never picked, Make default toasts "“Moonlight” has no layout chosen yet. Use Layout first." and changes nothing. An edited-in-place layout gets the Export toast instead.
• Before the first sync (no Moonlight shortcut yet): the moon, Layout and Make default are disabled; the launch line reads "Open Moonlight · Sync once to enable" and Advanced's text "None. Sync once, then set up Moonlight's Layout and press Make default".
• While a game runs every icon and both layout buttons still work.

16. Updating from the plugin (update spec 3.9, V1 to V7)

Every item here is the user's check, on a device; none is a merge criterion. Off-device the updater is covered (updates.test.ts over tests/fixtures/update/releases.json, decky.test.ts for the allowlist and the call's arguments, controller.test.ts "the updater" for the check, the refusals and the order check (on a branch), stage, leave the page, then ask Decky, test_hard_rules.py for hard rule 12's greps, test_backend_updates.py for the staging); the backend's download on the device, Decky's own dialog, its install from the staged file, the uninstall and the reload are what these check. Since the staged hand-off (update spec 3.12.5) every install downloads first: the button reads Downloading…, then the page closes and Decky's dialog opens.

The first release with the updater cannot be updated to anything, since nothing newer exists yet. V1 to V5 therefore use Settings → Updates → Install another version → the installed version (reinstall), which takes the same route with install type 1 (Decky's dialog then says "reinstall" rather than "update"). The first real update, with the panel's Update to … row and the toast, is checked when the release after it ships; repeat V1, V2 and V5 then.

Start with the build installed by install.sh (every file root-owned), the plugin on, synced, a SteamGridDB key set and a default layout set, and an SSH session tailing Decky's log (journalctl -u plugin_loader -f). Before V1, copy what V4 compares: ~/homebrew/settings/Moonlight Sync/ (settings.json, pending.json, layouts.json, ignore.json), ~/.config/moonlight-steam-sync/, ~/.cache/moonlight-steam-sync/ and the library's tile count.

• The page. Settings shows Updates between Advanced and About: Installed is the plugin's version, Latest says "Up to date · checked today HH:MM" (or the newer release, once there is one), Check now asks again (a second press within a minute asks nothing), Check for updates automatically is on, and Install another version lists only releases from 0.12.0 up. About has a Decky Loader row with the loader's version.
• V1. [verify] The download, Decky's dialog, then the install. Install another version → the installed version: the button reads Downloading… while the plugin's backend downloads and checks the zip (the plugin's log shows stage_update v…: staged …), then Decky's dialog asks "Are you sure you want to reinstall Moonlight Sync …?" (on a real update: "…update Moonlight Sync to version X?"). Confirm: Decky installs the staged zip from ~/homebrew/data/Moonlight Sync/update/staged/, on loader v3.2.9 (§17's V8 is the same check for a branch build). If the dialog never appears, or Decky's log shows an error, escalate with both logs.
• V2. [verify] The page closes first, the plugin comes back. The settings page is gone before Decky's dialog shows (Decision U4). After Confirm the plugin reloads at the chosen version (About), with no loader or Steam restart. If the screen shows anything else (a blank route, a frozen page), escalate with what it showed.
• V3. [verify] Over both kinds of install. V1 over the copy install.sh put there (root-owned), then once more over the copy Decky just installed. Both work; if either fails, escalate.
• V4. [verify] Nothing of yours changes. Blocking. After the update: settings.json, pending.json, layouts.json and ignore.json are what they were, the key file is there with mode 0600 (Artwork → Test accepts it), the CLI's config and caches are unchanged, the default layout is still set (Advanced), and the library has the same tiles, Stream buttons and Streaming tab. Anything different: escalate, and it blocks the release.
• V5. Cancel. Start an install and press Cancel in Decky's dialog: the old version keeps running, the page's buttons are usable again, and a second attempt opens the dialog again (the zip already staged is not downloaded twice: the plugin's log says "already staged"). Then start one and press the page's own Cancel under Downloading… at once: no toast, no dialog, the buttons are usable again.
• V6. Where the plugin lands. After a Confirm, note where Moonlight Sync sits in Decky's plugin list (expected: at the end, §2.3 of the update spec) and whether a hidden or frozen state it had in Decky's list survived. Write what you see into the README's "Updating" section.
• V7. Offline. With Wi-Fi off, start an install: the download fails before Decky is asked, a toast says "Could not reach GitHub: …", Decky's dialog never opens, the settings page stays, and the old version still runs (Decky has nothing to download, so its progress never shows). If Decky's dialog or progress appears, escalate. Back online, the install works.
• The check's toast and the panel's row (once a newer release exists). A plugin load (restart Steam) toasts "Version X is available. Settings → Updates" once, and the panel's last row reads Update to X; pressing it opens Settings → Updates. With Check for updates automatically off, a load toasts nothing and adds no row until Check now.
• Off. With the plugin toggled off: no toast at load, no row, and the settings route has no Updates page (§12).

17. The staged hand-off and the channels (update spec 3.12.5, V8 to V10)

Every item here is the user's check, on a device, before a release with the channel picker is cut; none is a merge criterion. Off-device the staging is covered (test_fetch.py, test_updates.py, test_backend_updates.py over file:// trees), and so are the order check, stage, leave, ask, the forced check on a branch channel, a failed staging, Cancel and the picker (controller.test.ts), and the allowlist's file:// rule (decky.test.ts); Decky's install from a file:// path, the picker's modal and a real branch build are what these check.

Start as for §16 (the plugin on, synced, a key and a default layout set, Decky's log tailed), with main publishing builds (build-main exists on the repository's releases, with a build.json among its assets). Keep an SSH session for V10's moonlight-steam-sync --version and sha256sum ~/.local/bin/moonlight-steam-sync.

• The picker. Settings → Updates' second row is Channel, reading Releases, with the description "Releases are tested. Builds of a branch are whatever was pushed last." Its list has Releases, then main, then any other branch with a build. Choosing main asks "Follow main?" ("Builds of a branch are untested and can break syncing. You can return to Releases here at any time.", Follow / Cancel). [verify] Cancel leaves Releases selected in the dropdown (whether Steam's dropdown snaps back to the stored channel after a cancelled confirm is unmeasured) and asks GitHub nothing. Choosing Releases from a branch asks nothing.
• The branch's build.json through the loader's fetch. The build.json request is the plugin's first request through Decky's fetchNoCors to github.com/…/releases/download/…, which answers with a redirect (302) to another host; every request before it went to api.github.com, which does not redirect. Follow main (the picker checks at once): Latest must show the build, main @ <sha7> · built … · checked …, not "No build of main is published". If it shows the latter although build-main has a build.json, the loader's fetch did not follow the redirect (the check reports no error then, since a failed second request never fails it): escalate with Decky's log.
• A new build of the followed branch is seen at once. With main followed and its build installed, merge to main (or gh workflow run builds.yml --ref main) and wait for the Builds run to finish; Check now on the Updates page must show the new commit, main @ <the new sha7>, and offer Switch to it. Before amendment A6 the loader's fetch went through CEF's HTTP cache, which kept the old build.json (served with Last-Modified and no Cache-Control) for hours: the page said Up to date although main had moved, and, once the new build was installed through Releases and back, offered the previous commit for as long. Found on the Deck 2026-09-29; journalctl -u plugin_loader shows a Preparing GET request to …/build-main/build.json line for a check that reached the loader, and none for one the cache answered.
• V8. [verify] A file:// artifact installs. On main, press Switch to main @ : Downloading…, then the page closes and Decky's dialog asks to overwrite Moonlight Sync with version " (main @ )"; Confirm. Decky installs the zip from ~/homebrew/data/Moonlight Sync/update/staged/ (a path with a space in it) through utilities/install_plugin, and the plugin reloads. If Decky refuses the artifact, cannot open the path, or its log shows an error: escalate with the log. The fallback the spec allows then (update spec 3.12.5, not built): releases keep the URL route of update spec 3.5, and branch builds hand Decky the release asset's URL after a successful staging, which has then proved what the URL serves.
• V9. Follow main, install, a second push, back to Releases. After V8: Installed reads <version> · main @ <sha7> · built …, Latest says "Up to date · checked …" and there is no install button. Push a commit to main, wait for builds.yml to publish it, then restart Steam (or press Check now a minute later): the toast "Version main @ is available. Settings → Updates" and the panel's row appear, and Switch to main @ installs it. Then choose Releases: Latest names the newest release and the button reads Switch to ; pressing it installs the release (Decky asks to overwrite) and Installed reads the plain version again. Anything else: escalate.
• V10. The CLI at each step of V9. Before V8, after V8, after the second push's install and after the return to Releases, note moonlight-steam-sync --version and the sha256 of ~/.local/bin/moonlight-steam-sync, and About's CLI rows. Expected: the version stays the release's number throughout; the bytes change to the branch build's bundled CLI after V8 and after the second push's install (a build of the same version with other bytes replaces it, README "The bundled CLI"), and go back to the release's after the return to Releases. Anything else: escalate.
• A failed staging leaves everything as it was. With Wi-Fi off, press Switch to … on main: the forced check fails first, a toast says "Could not reach GitHub: …", nothing downloads, Decky's dialog never opens. Back online, press it and at once the page's Cancel under Downloading…: no toast, no dialog, and a second press works.
• A build made on the device is the commit it is (update spec amendment A5). On the device, clone main afresh, build it (pnpm install, pnpm run build, backend/entrypoint.sh, scripts/package.py --require-cli) and install the zip by hand (README "Manual install"). package.py must print package.py: build.json from git: main @ <sha12>; if it prints no build.json: … instead, the text in brackets is git's own reason (a clone that belongs to another user is "dubious ownership"): report it. Then, with the Channel on main and build-main published from that same commit: Installed reads <version> · main @ <sha7> · built …, Latest says "Up to date · checked …" and there is no install button; Settings → About's Built from reads main @ <sha7> · built … and Commit is the whole commit, the one git rev-parse HEAD printed in the clone. Before this, such a build always showed Switch to main @ (found 2026-09-28). With the Channel on Releases the page offers Switch to instead, as for any branch build.