--- name: adom-screensaver-rationale description: The WHY behind adom-screensaver, the necessity-is-the-mother-of-invention origin story (keeping /remote-control alive without burning in the screen), the justification for every behavior, the staged 2-min-billboard → 5-min-display-off cascade, power-aware keep-awake, the lock-on-wake rule, the wiki-billboard "advertise apps" concept, and the org-aware personalized vision. Read this when reasoning about WHY the screensaver behaves a certain way, defending or changing a behavior, explaining its purpose to someone, or deciding whether a proposed change respects the original intent. Triggers, why does the screensaver, screensaver reasoning, screensaver rationale, why was adom-screensaver built, screensaver justification, why keep-awake, why does the screen stay on, screensaver cascade, why billboard, screensaver design, screensaver purpose. metadata: node_type: skill --- Parent skill: **adom-screensaver** This is the **design rationale**, the *why*. For *how* to operate/build/extend, see the sibling skills (`adom-screensaver` operate, `-billboard`, `-wake`, `-build`). When a change is proposed, check it against the reasoning here first: most "obvious simplifications" regress a behavior that exists for a hard-won reason. ## Necessity is the mother of invention, the origin John kept getting burned by a specific failure: he'd start a **`/remote-control`** thread in Claude Code, then walk away from the laptop, go to dinner with the family, and come back to a **dead session**. The laptop had gone to **sleep and killed the session**, *even while plugged in*. The AI had stopped working the moment he left. The naive fix made it worse: force the laptop to never sleep → now the **screen never turns off** either → he was **burning in his display** just to keep a vibe-coding session alive. Lose-lose: either the session dies, or the panel cooks. adom-screensaver exists to dissolve that trade-off. The core insight is that **"machine awake" and "screen on" are two different things**, and Windows' defaults conflate them. The screensaver splits them: hold the **machine** awake (network + `/remote-control` survive) while letting the **screen** turn off to save power. Best of all worlds, the thing Windows wouldn't give you out of the box, because its power model predates AI agents that run for hours on your behalf. ## What each behavior is FOR (don't regress these) - **Power-aware keep-awake.** Plugged in → hold the machine awake indefinitely (`/remote-control` runs as long as you like, your laptop becomes a *vibe-coding server*). On **battery** → stay passive and let Windows' own idle-sleep timer be the give-up clock (default 30 min), so a forgotten laptop in a bag eventually sleeps instead of draining flat. The keep-awake holds `ES_SYSTEM_REQUIRED` only on AC; it deliberately does **not** assert it on battery. See the power decisions in the project memory before changing this, it regressed twice. - **Lid-close = "Do nothing".** Closing the lid is a hardware *button action*, separate from idle sleep, keep-awake can't influence it. Set the lid action to "Do nothing" so closing the lid to walk to the next room doesn't instantly sleep; the idle-sleep timer (30 min on battery) is the real give-up. Walk around freely; come back within 30 min and nothing was interrupted. - **Lock rule: "no sleep → no lock; real sleep → normal sign-in."** `ScreenSaverIsSecure=0` so dismissing the billboard / reopening the lid (no sleep occurred) drops straight to the desktop, no password. `CONSOLELOCK` is left at Windows' default so waking from an *actual* sleep still asks to sign in. (CONSOLELOCK is admin-only to change; do not try to disable it.) ## The staged cascade (the 2-min → 5-min design) The saver runs in **stages**, on purpose, a gentle cascade rather than a hard cut to black: 1. **0-2 min idle:** nothing. (`ScreenSaveTimeOut = 120s`.) 2. **2-5 min idle:** the **billboard** plays, a *dim, mostly-black* full screen cycling recent wiki drops. This phase is **lightweight to dismiss**: the panel is still powered, so a single mouse flick or keypress expires it instantly. 3. **5 min idle:** the **display powers off** entirely (`monitor timeout = 300s`) to actually turn the display off. The machine stays awake (on AC) the whole time. **Why this ordering matters:** the saver often kicks in when you didn't really want it (you paused to read, took a call). If the *first* thing it did was fully power the screen off, every accidental trigger would cost you the heaviness of the panel going dark and then warming back up. By showing a dim billboard first and only powering the screen off 3 minutes later, an early/accidental trigger is trivially undone, you barely notice it. The full display-off is reserved for when you've truly stepped away. Don't collapse the two stages into one. ## The screensaver became a canvas, the billboard Once you have a full screen that's "resting," it's the **perfect canvas**. Instead of black, the billboard surfaces the **coolest new stuff in the Adom Wiki**, each app/skill's hero image, title, and a "just ask Claude: `install `" prompt. So the screensaver does double duty: it keeps the machine working *and* **educates the user (and John) about new wiki apps while they're away**. This reframes wiki hero images as **marketing surfaces**: your wiki assets advertise apps on people's lock screens and nudge adoption, value far beyond the wiki page itself. - **Media:** a **video hero** (`.webm`) is **streamed silently** (muted, looped) straight from the wiki, motion grabs the eye; nothing is downloaded. No video → fall back to the **hero image**. - **Dual-wiki:** pulls Wiki v2 (canonical) + Wiki v1 (legacy, with a "migrate to v2" nudge); v2 wins on overlap. Order is shuffled each run so the first slide varies. - **Curation:** a runtime `exclude.txt` drops baseline/uninteresting slugs without a rebuild. ## The vision this is part of - **Personalized, org-aware billboards.** Today the billboard advertises *public* wiki pages. Next: HD hands the saver the user's Adom login, passed through on wiki queries, so the billboard shows **public + the user's org-private apps**. An NTX Embedded user sees NTX's own apps; someone in multiple orgs sees the union. The wiki becomes a personalized, org-aware app store, and the screensaver is its ambient discovery surface. - **Distributed via the wiki, installed by HD.** The screensaver is a Windows-*host* app, so it's not `adompkg install`-into-the-workspace. It's published to Wiki v2 with a `dist/win/` bundle in the tarball; HD's setup steps fetch + install it on the host (opt-in, reversible). Publish a new version → every HD picks it up, no HD rebuild. (macOS/Ubuntu HD must gracefully skip it, it's Windows-only.) ## Use cases to keep in mind - **Vibe-coding server:** laptop plugged in on a desk, lid open or closed, running `/remote-control` threads for hours while John is elsewhere. Never sleeps; the display turns off. - **Mobile / on battery:** moving between rooms or out the door, rides short lid-closings, then sleeps on the 30-min give-up so it doesn't drain. - **Ambient discovery:** any idle moment becomes a chance to learn what's new in the wiki. **Guiding principle:** the screensaver bends the laptop's behavior away from Microsoft's pre-AI defaults, *on purpose*, to protect long-running AI work, while being honest about power (turn the display off, respect the battery, keep real-sleep security). Any change should preserve that balance.