docs: a desktop the layout never saw, and the television check only a room can do

What Tiny Pebbles showed, what the lab measured (a new activity gives the
same bare desktop; a file path as the fallback is ignored; live D-Bus is
refused by the lockdown), the two parts of the fix, and the check with a
real television switched on after a reboot — the one thing the lab cannot
do, because KWin will not start with no screen.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

docs/testing.md

@@ -11,6 +11,39 @@ before promoting to stable with `./update_stable.sh`.
 - [ ] Dock appears, centred
 - [ ] Clock appears, bottom right
 
+### The television switched on after a night-time reboot
+
+This is how Tiny Pebbles lost its wallpaper after the 0.2.2 upgrade, and
+the lab cannot do it: KWin will not start a session with no screen, and
+the lab cannot plug one in. The lab proves the same code path through a
+new activity (`tools/lab/wallpaper-check`); only a real television
+proves that switching it on takes that path. See
+[ui-scale.md](ui-scale.md#a-desktop-the-layout-never-saw-0266). Do it once, on a
+desktop whose television is switched off at the set, not the remote:
+
+1. [ ] Television **off** at the set. `sudo reboot`, and wait five minutes.
+2. [ ] Television **on**. The classroom's landscape is on the screen,
+       **not** Plasma's purple wallpaper. The panel is the room's own.
+3. [ ] From the maintenance terminal (Meta+Ctrl+Alt+Shift+K),
+       `classroom-desktop-wallpaper --check`. Note what it says. If it
+       names a desktop that "had no wallpaper configured", the television
+       really did arrive after the shell, and the screen in step 2 is the
+       fix working
+4. [ ] `systemctl --user restart plasma-plasmashell.service`: the panel
+       blinks and comes back, open windows stay, the wallpaper is unchanged
+5. [ ] `classroom-desktop-wallpaper --check` now says "the classroom
+       wallpaper already"
+6. [ ] Reboot with the television on: the same picture and the same panel
+
+Tiny Pebbles can confirm the cause **before** it takes the release, because
+the update reboots it and a login rebuilds the file. If its panel was built
+with no screen, the panel is `[Containments][1]` next to the desktop's 10:
+
+```
+grep -A6 '^\[Containments\]\[[0-9]*\]$' \
+    ~/.config/plasma-org.kde.plasma.desktop-appletsrc | grep -E '^\[|^plugin='
+```
+
 ## Provisioning
 
 - [ ] `journalctl -u ekklesia-classroom-provision` shows a clean run

docs/ui-scale.md

@@ -47,6 +47,69 @@ package installs it at `/usr/share/backgrounds/ekklesia/classroom-calm.png`, the
 path used by the packaged Plasma layout. The layout is rebuilt at login, so
 upgraded classrooms receive the package wallpaper without per-room copying.
 
+### A desktop the layout never saw (0.2.6.6)
+
+Tiny Pebbles came through the 0.2.2 → 0.2.6.4 upgrade showing Plasma's own
+purple wallpaper. Its desktop was containment 10 with no `Wallpaper` group;
+River Kids' is containment 1 with one. The package and the picture were the
+same on both.
+
+The layout sets the wallpaper on the desktops that exist *while it runs*.
+Plasma makes a desktop for every screen or activity that appears later, and
+it makes those without the layout. 0.2.2's updater rebooted as soon as it
+had installed, at 03:00–03:30. A television switched off at the set is
+usually no screen at all, so the layout would have run with no desktop, and
+the desktop Plasma made when the television came on was bare. A panel built
+with no screen takes number 1 and its eight applets 2–9, which is exactly
+how a desktop ends up as 10. **The television is inferred, not observed**.
+See the hardware check in [testing.md](testing.md#the-television-switched-on-after-a-night-time-reboot).
+
+Measured in the lab (Plasma 6.3.6, Debian 13):
+
+| What was tried | What happened |
+| --- | --- |
+| Activity manager delayed 20 s at login | Plasma waited for it; desktop 1, wallpaper right. Not the cause |
+| A new activity created mid-session | Plasma made desktop 11 with no `Wallpaper` group, the same shape as Tiny Pebbles' 10. The screen showed Plasma's *Next*; the panel was untouched |
+| Look-and-feel default `Image=` set to a **file path** (0.2.2–0.2.6.5) | Ignored. `DefaultWallpaper` in libkworkspace6 looks the value up as a wallpaper **package** under `wallpapers/<name>`, the way Breeze says `Image=Next` |
+| The same default set to a **package name**, whose one image links to the file | Desktop 11, still with no `Image`, showed the classroom's picture after a shell restart |
+| Setting it live over D-Bus (`evaluateScript`, `plasma-apply-wallpaperimage`) | Refused: "Widgets are locked". The classroom's lockdown forbids the scripting console, and it stays forbidden |
+| Disabling the only screen to reproduce a screenless start | KWin refuses ("Disabling all outputs … is not allowed"), and the nested lab cannot hot-plug a screen |
+
+So there are two parts, and they do different jobs:
+
+* **The default is now a package**, `/usr/share/wallpapers/EkklesiaClassroom`.
+  Its image is a link to the file above, and the look and feel names it.
+  Any desktop Plasma makes without the layout shows the classroom's picture
+  with nothing having to run. This is the fix for Tiny Pebbles.
+* **`classroom-desktop-wallpaper`** writes `wallpaperplugin=org.kde.image` and
+  the classroom `Image` into every desktop containment already in the file,
+  so the configuration says what the screen shows. It finds desktops by
+  plugin (`org.kde.plasma.folder`, `org.kde.desktopcontainment`), never by
+  number. It changes nothing else, and it does not write a file that is
+  already right. It runs as plasmashell's `ExecStartPre`, the one moment
+  the shell does not own the file: every login, every reboot, every restart
+  after a crash. At a login it usually finds nothing, because
+  `classroom-desktop-reset` has just removed the file for the layout to
+  rebuild.
+
+To apply it in a running session without logging out, from the maintenance
+terminal:
+
+```
+classroom-desktop-wallpaper --check                   # read-only
+systemctl --user restart plasma-plasmashell.service   # the panel blinks, windows stay
+```
+
+Run without `--check` while the shell is up, it refuses and prints that
+second line rather than edit the file underneath the shell.
+
+Tests: `tests/test-classroom-desktop-wallpaper.sh` (in the build) covers
+Tiny Pebbles' own file, a healthy River Kids file, differing numbers,
+idempotence and the guard. `tools/lab/wallpaper-check` covers real Plasma,
+reading the colour off the screen, and runs inside `tools/lab/dirty-upgrade`.
+`tools/validate-trixie-release.sh` covers the installed package when
+upgrading from a previous release.
+
 ## What the one number reaches
 
 `classroom-ui-scale` prints it, clamped, and everything that cannot read