Adom Hydrogen

@@ -0,0 +1,65 @@+# How Hydrogen Desktop Auto-Updates++Hydrogen Desktop keeps itself, its skills, and its content current from the Adom Wiki. This+page is the canonical inventory of every mechanism that phones home: what it fetches, when,+how big the payload is, and how the schedules are designed so a large fleet cannot+accidentally denial-of-service the wiki with synchronized requests.++## The mechanisms++| # | What updates | Trigger and cadence | Endpoint | Payload |+|---|---|---|---|---|+| 1 | **The HD app itself** | 20 s after launch, then every 4 h (launch-anchored timer) | `version.json` on this page | ~1 KB manifest; the ~100 MB signed installer downloads ONCE per new version, SHA-256 verified, background-staged |+| 2 | **Lightbulb prompt list** | Opening the menu (debounced to 15 min) plus a background tick every 30 min that fetches only if 4 h stale AND Mon-Fri 7am-7pm local; manual refresh button bypasses the debounce | `lightbulb-prompts/prompts.json` on this page | ~10 KB |+| 3 | **Workspace packages + skills** (inside the container) | The registry hook runs `adom-wiki pkg update` on user activity, throttled to ~30 min; nothing fires while the machine is idle | wiki package registry | manifests are KBs; package tarballs only when versions changed |+| 4 | **code-server drift check** | After launch: 90 s cadence for a short early window, then every 30 min | workspace-internal, wiki only if drift found | tiny |+| 5 | **Adom Desktop + its bridges** (AD is its own app) | On AD launch, then every 4 h per bridge page | each bridge's wiki page | manifests; binaries only on version change |+| 6 | **Setup cascade** (one-time) | The `update-packages` step runs once per install/setup, not periodically | wiki package registry | whatever the image is behind by |++Update mode for #1 is user-controlled (Settings → Hydrogen Desktop → Updater): Normal shows a+banner and you choose when to restart; Forced is reserved for important fixes; Off disables+the check entirely.++## Why the fleet cannot DoS the wiki (design rules)++1. **Every periodic timer is launch-anchored, not wall-clock-anchored.** A 4 h timer starts+   counting from the moment that particular machine launched HD. Launches are naturally+   spread out, so across a fleet the polls are approximately uniformly distributed in time.+   No timer fires "at the top of the hour" by design.+2. **Manifests are tiny, binaries are fetched once.** The recurring traffic is 1-10 KB+   manifest reads. The heavy installer download happens exactly once per released version per+   machine, gated by a SHA-256 comparison, and is spread across each machine's next 4 h poll+   window rather than all at once.+3. **Activity gating.** The container package hook fires on user prompts (throttled), so idle+   machines generate no traffic. The lightbulb background tick is additionally gated to+   business hours, and any user-driven check (menu open) debounces to 15 minutes and+   satisfies the background timer's freshness window too, so the two paths never double-poll.+4. **Cloudflare fronts the wiki.** The static file and download paths are CDN-cacheable, so+   even a correlated read burst of the same manifest mostly terminates at the edge.+5. **Releases are gated before they are advertised.** The release pipeline refuses to publish+   a `version.json` that points at a missing installer (HEAD-checked first), so the fleet is+   never sent chasing 404s on a retry loop.++## Known herding risks (honest list, with status)++- **Phase alignment after an update wave.** When a release ships and the whole fleet+  restarts within a short window, every machine's launch-anchored 4 h timer becomes roughly+  phase-aligned and stays that way until the next uncorrelated restart. A fleet of N then+  polls the ~1 KB manifest in a burst every 4 h. At current fleet sizes this is noise, and+  the CDN absorbs it; at much larger scale the fix is jitter (below).+- **Morning boot storms.** Office machines powered on together Monday 9am launch together,+  which briefly correlates the launch-anchored timers. Same magnitude and mitigation as+  above.+- **The business-hours gate clusters its opens.** The lightbulb tick's Mon-Fri 7am-7pm gate+  means the subset of machines whose 30 min tick lands just after 7am local all fetch within+  that first half hour. Bounded by the tick spread, ~10 KB each, per timezone.+- **Planned hardening (not yet implemented):** add ±10-15% random jitter to the fixed+  intervals (HD updater, lightbulb tick, AD bridge sync), send `If-None-Match`/ETag on+  manifest reads so unchanged polls are 304s, and if the fleet grows large, stagger releases+  by advertising `version.json` to cohorts instead of everyone at once.++## For contributors++If you add ANY new periodic fetch to HD, follow the design rules above (launch-anchored,+debounced, activity- or hours-gated where sensible, tiny manifest + fetch-once binary) and+add it to the table on this page in the same PR.