Adom Bridge

@@ -0,0 +1,103 @@+# Adom Desktop and Hydrogen Desktop++Adom Desktop (AD) is a full product on its own: a standalone tray app that lets+AI assistants and remote sessions drive your Windows machine. Hydrogen Desktop+(Hydrogen) is a sibling app that bundles AD inside its own installer and runs it in+"embedded" mode. This page explains what that relationship looks like from your+chair: what you see, what happens when Hydrogen closes or crashes, and who is in+charge of what.++![The vivid Hydrogen Embedded taskbar tile](taskbar-embedded.png)++## How Hydrogen runs AD++Hydrogen's installer carries the signed AD installer and silent-installs it to the+normal location (`%LOCALAPPDATA%\Adom Desktop`). At runtime Hydrogen launches AD with+the `--embedded` and `--start-hidden` flags and connects it to Hydrogen's own relay.+From that point Hydrogen owns the user-facing surface: the window you interact with+is Hydrogen's, and AD works quietly underneath it.++AD keeps doing everything it normally does while embedded: serving its local+API, running bridges, connecting to relays. Embedded is a display state, not a+different program.++## What you see while embedded++- **No separate AD window or tray icon.** AD hides both so that Hydrogen reads as+  the one app. AD is still running and serving.+- **The taskbar tile changes.** AD's window identity flips from the muted+  "Adom Desktop" tile to a vivid teal tile named "Adom Desktop Hydrogen Embedded".+  The swap happens in about a second, with no restart. The tile is the+  at-a-glance signal of which mode AD is in.+- **A locked connection row.** In AD's Connections list, the relay entry Hydrogen+  created is marked "Managed by Hydrogen". You cannot edit, disconnect, or remove it+  while embedded, because doing so would break the embedded session. AD's+  backend refuses those changes everywhere (including remote commands), not+  just in the UI. The entry is temporary: it is re-added each time Hydrogen launches+  AD and goes away when AD returns to standalone.++## When Hydrogen closes or crashes++AD is designed to stay up. This is deliberate: AD is the recovery channel for+the machine it runs on. As long as AD is alive, a remote agent can read a log,+check what is installed, relaunch something, or roll back a bad update. If AD+exited whenever Hydrogen exited, one bad Hydrogen exit would leave the machine unreachable+until someone physically walked to it.++So:++- **Hydrogen closes normally.** Hydrogen tells AD it is releasing it, and AD reverts to+  standalone on the spot: the tray icon comes back, the taskbar tile returns+  to the muted standalone look, and AD's relay connections are preserved.+- **Hydrogen crashes or is killed.** AD notices on its own (it probes Hydrogen every 10+  seconds and waits for three consecutive misses, about 30 seconds, so a quick+  Hydrogen restart does not bounce it) and then reverts to standalone the same way.+  Your machine stays reachable.+- **The only thing that exits AD is an explicit shutdown**: the+  `desktop_shutdown` command, or you closing AD yourself. There is a launch+  flag (`--exit-when-hd-exits`) that would make AD exit alongside Hydrogen, but Hydrogen+  does not pass it, and there is no setting for it. In practice AD always+  survives its parent.++One caveat: because AD runs as Hydrogen's child process, an operating-system level+"kill the whole process tree" takes AD down with Hydrogen instantly. That is the OS+at work, not AD's behavior, and it is rare in normal use.++## Updates while embedded++AD updates itself even when embedded, but the timing is shared:++- **AD stages.** AD checks for new versions, downloads the installer, and+  verifies its SHA-256, so a verified update sits ready on disk with no+  network needed to apply it.+- **Hydrogen triggers.** Hydrogen decides the safe moment and tells AD to apply the staged+  update. Embedded AD never restarts itself for an ordinary update; Hydrogen owns+  the restart timing so it does not interrupt your work.++When AD is standalone, it handles both halves itself according to your update+preference (prompt, auto, or off).++## Permissions while embedded++When a remote AI session asks AD to run something sensitive (a shell command,+a script, a file write), someone has to approve it. Embedded, that someone+sees the prompt in Hydrogen:++- Hydrogen tells AD at startup whether commands should be auto-approved. Unless you+  have opted in to auto-approval, AD forwards each sensitive request to Hydrogen,+  and Hydrogen shows the approval prompt. AD shows no dialog of its own, so you are+  never confused by a window from an app you did not think you were running.+- Your choices in Hydrogen's prompt (allow once, allow for 1 or 24 hours, bypass+  while running, or deny) are applied by AD exactly as decided.+- If Hydrogen is ever unreachable at the moment of a request, AD falls back to its+  own approval dialog rather than silently approving or silently blocking.++Only remote (cloud) callers are gated this way. Local software on your own+machine, including Hydrogen itself, is trusted the way any installed app is.++## Standalone is the full product++Nothing above is a limitation of AD. Installed on its own, AD is the complete+experience: its own window, tray icon, connections panel, bridges sidebar,+approval prompts, and self-updates. Embedding changes who draws the window and+who picks the update moment; it does not change what AD can do.