Adom Screensaver

---
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 <x>`" 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.