Adom Bridge

@@ -1,116 +1,116 @@-# Sign-in and cloud configuration
-
-Adom Desktop connects your Windows PC to your cloud containers so an AI in a
-container can work with your machine. The fastest way to set that up is your
-Adom account: sign in once, and your registered containers appear in Adom
-Desktop automatically. No JSON, no copied URLs, no manual configuration.
-
-![The Connections panel with signed-in servers](main-view.png)
-
-This page explains what you will see during sign-in, how your containers show
-up on their own, and what the AI in your container runs on its side.
-
-## Signing in
-
-Open Adom Desktop. If you are not signed in, the Connections panel shows a
-prominent "Sign in to Adom" button (there is also a sign-in link in the
-footer). Click it. Here is what happens:
-
-1. Your default browser opens on the Adom approval page.
-2. You approve the sign-in there, using your Adom account.
-3. Adom Desktop waits in the background (it polls for up to 15 minutes) and
-   picks up the session the moment you finish in the browser.
-
-Your session is saved locally at `~/.adom/session.json`, so you stay signed in
-across restarts.
-
-On a fresh launch when you are signed out, Adom Desktop helps you along: it
-shows a short countdown ("Logging you into Adom in 5, 4, 3, 2, 1", with a
-Cancel button) and then opens the sign-in page for you.
-
-If something goes wrong in the browser (for example, you picked the wrong
-account), Adom Desktop shows a banner in the window with a Retry button. A
-common cause is choosing a personal account instead of your Adom account, so
-pick the right one and retry.
-
-## The zero-JSON promise
-
-Once you are signed in, Adom Desktop pulls the list of containers registered
-to your Adom account and adds them to your Connections list by itself:
-
-- Right after you sign in: your containers appear immediately and Adom
-  Desktop connects to them right away. You should see the connection light go
-  green within seconds.
-- On every launch while you are signed in: Adom Desktop re-reads your account
-  at boot, so a container registered yesterday shows up today without any
-  action from you.
-
-Because the registration lives in your account (not on any one machine), it
-survives reinstalls and follows you to a new PC: install Adom Desktop, sign
-in, and your containers are back.
-
-## How a container gets into your account
-
-You do not add containers by hand. The AI running inside your Adom cloud
-container registers itself, using a one-line command that writes the
-connection into your account. After that, the flow on your side is just:
-
-1. Install Adom Desktop on Windows (from
-   `https://wiki.adom.inc/adom/adom-desktop`).
-2. Sign in with your Adom account.
-3. The container appears in your Connections list and connects automatically.
-
-If Adom Desktop was already installed and signed in when the container
-registered itself, restart it (or wait for the next launch, which re-reads
-your account) to see the new entry.
-
-## For the AI in your container
-
-If you are the AI setting up the connection, run the one-command setup first:
-
-```bash
-adom-desktop setup_desktop
-```
-
-(Aliases: `setup`, `connect`.) It auto-detects this container's public relay
-URL and returns a ready-to-run `register_command`, plus a fallback
-`server_config` JSON and the installer URL. Run the `register_command`; it is
-`register_container` with the name and URL filled in:
-
-```bash
-adom-desktop register_container '{"name":"my-container","url":"wss://<container-slug>.adom.cloud/proxy/8765/"}'
-```
-
-`register_container` authenticates with the account token that Adom mounts at
-`/var/run/adom/api-key` and writes the connection into the user's cloud
-profile (the `desktop.container.<id>`, `desktop.last_slug`, and
-`desktop.enabled` settings). It only works on Adom cloud containers; anywhere
-else it returns `ok:false` with an explanation. It is idempotent by URL:
-registering the same URL again refreshes the existing entry instead of
-creating a duplicate, so call it once per container.
-
-Keep the relay running so the desktop has something to connect to, then
-verify:
-
-```bash
-adom-desktop serve --supervise
-adom-desktop targets
-```
-
-## Fallback: paste the server JSON
-
-If the container is not an Adom cloud container (or you prefer not to sign
-in), you can add the connection manually. The AI gives you the
-`server_config` JSON from `setup_desktop`; paste it into the Connections
-panel's "Paste server JSON to add" box and press Enter. The server appears
-and connects, shown by a green dot. Use the JSON exactly as provided.
-
-Note that each container has its own relay: a new container needs its own
-entry, and entries from old containers will not work for it.
-
-## Signing out
-
-Use the Sign-out link in Adom Desktop. It clears the saved session at
-`~/.adom/session.json`. After signing out, your account-registered containers
-stop syncing until you sign in again. (Programmatic callers can do the same
-with the `desktop_logout` verb.)
+# Sign-in and cloud configuration++Adom Bridge connects your Windows PC to your cloud containers so an AI in a+container can work with your machine. The fastest way to set that up is your+Adom account: sign in once, and your registered containers appear in Adom+Desktop automatically. No JSON, no copied URLs, no manual configuration.++![The Connections panel with signed-in servers](main-view.png)++This page explains what you will see during sign-in, how your containers show+up on their own, and what the AI in your container runs on its side.++## Signing in++Open Adom Bridge. If you are not signed in, the Connections panel shows a+prominent "Sign in to Adom" button (there is also a sign-in link in the+footer). Click it. Here is what happens:++1. Your default browser opens on the Adom approval page.+2. You approve the sign-in there, using your Adom account.+3. Adom Bridge waits in the background (it polls for up to 15 minutes) and+   picks up the session the moment you finish in the browser.++Your session is saved locally at `~/.adom/session.json`, so you stay signed in+across restarts.++On a fresh launch when you are signed out, Adom Bridge helps you along: it+shows a short countdown ("Logging you into Adom in 5, 4, 3, 2, 1", with a+Cancel button) and then opens the sign-in page for you.++If something goes wrong in the browser (for example, you picked the wrong+account), Adom Bridge shows a banner in the window with a Retry button. A+common cause is choosing a personal account instead of your Adom account, so+pick the right one and retry.++## The zero-JSON promise++Once you are signed in, Adom Bridge pulls the list of containers registered+to your Adom account and adds them to your Connections list by itself:++- Right after you sign in: your containers appear immediately and Adom+  Desktop connects to them right away. You should see the connection light go+  green within seconds.+- On every launch while you are signed in: Adom Bridge re-reads your account+  at boot, so a container registered yesterday shows up today without any+  action from you.++Because the registration lives in your account (not on any one machine), it+survives reinstalls and follows you to a new PC: install Adom Bridge, sign+in, and your containers are back.++## How a container gets into your account++You do not add containers by hand. The AI running inside your Adom cloud+container registers itself, using a one-line command that writes the+connection into your account. After that, the flow on your side is just:++1. Install Adom Bridge on Windows (from+   `https://wiki.adom.inc/adom/adom-desktop`).+2. Sign in with your Adom account.+3. The container appears in your Connections list and connects automatically.++If Adom Bridge was already installed and signed in when the container+registered itself, restart it (or wait for the next launch, which re-reads+your account) to see the new entry.++## For the AI in your container++If you are the AI setting up the connection, run the one-command setup first:++```bash+adom-bridge-cli setup_desktop+```++(Aliases: `setup`, `connect`.) It auto-detects this container's public relay+URL and returns a ready-to-run `register_command`, plus a fallback+`server_config` JSON and the installer URL. Run the `register_command`; it is+`register_container` with the name and URL filled in:++```bash+adom-bridge-cli register_container '{"name":"my-container","url":"wss://<container-slug>.adom.cloud/proxy/8765/"}'+```++`register_container` authenticates with the account token that Adom mounts at+`/var/run/adom/api-key` and writes the connection into the user's cloud+profile (the `desktop.container.<id>`, `desktop.last_slug`, and+`desktop.enabled` settings). It only works on Adom cloud containers; anywhere+else it returns `ok:false` with an explanation. It is idempotent by URL:+registering the same URL again refreshes the existing entry instead of+creating a duplicate, so call it once per container.++Keep the relay running so the desktop has something to connect to, then+verify:++```bash+adom-bridge-cli serve --supervise+adom-bridge-cli targets+```++## Fallback: paste the server JSON++If the container is not an Adom cloud container (or you prefer not to sign+in), you can add the connection manually. The AI gives you the+`server_config` JSON from `setup_desktop`; paste it into the Connections+panel's "Paste server JSON to add" box and press Enter. The server appears+and connects, shown by a green dot. Use the JSON exactly as provided.++Note that each container has its own relay: a new container needs its own+entry, and entries from old containers will not work for it.++## Signing out++Use the Sign-out link in Adom Bridge. It clears the saved session at+`~/.adom/session.json`. After signing out, your account-registered containers+stop syncing until you sign in again. (Programmatic callers can do the same+with the `desktop_logout` verb.)

@@ -0,0 +1,117 @@+# Bridge skill propagation: how a bridge's docs reach the AI++A bridge is code that runs on your Windows desktop, right next to Adom Bridge. It drives+KiCad, a browser, Blender, whatever app it was written for. It has to run there, because+that is where the app is.++The AI that calls the bridge does not run there. It runs in a cloud container, and that+is where it looks for its local skills (its documentation), in `~/.claude/skills/` or+`~/.codex/skills/`.++So installing a bridge onto your desktop hands the AI a set of new abilities it has no+documentation for. The runtime and the docs are two separate things, they end up in two+separate places, and they get there by two different routes. This page explains how they+find each other.++## The two artifacts++Every bridge publishes two things to its own wiki page:++| | The release zip | The skills package |+|---|---|---|+| What it contains | Server code plus `bridge.json` | Text documentation only, a few KB |+| Where it goes | The desktop | The cloud container |+| How it gets there | `bridge_install {manifestUrl}` streams it, unzips it, and spawns it | `adom-wiki pkg install adom/<slug>` |+| Where it lands | Adom Bridge's bridge cache | `~/.claude/skills/` and `~/.codex/skills/` |++Same bridge, two destinations, two mechanisms. Neither one substitutes for the other.+Installing the runtime does not give the AI docs, and installing the skills does not give+your desktop anything to run.++## How a container finds out which skill it needs++This is the piece that connects the two halves.++1. A bridge declares `docs` in its `bridge.json`, pointing at its own wiki page.+2. Adom Bridge derives the skill package name, `adom/<slug>`, from that `docs` URL. It+   takes the last path segment. (It deliberately does not derive the name from the+   manifest URL, which is owner-qualified and would give the wrong answer.)+3. `bridge_list` returns, for each bridge, a `skillPkg` field (the package name) and an+   `installSkill` field (the exact, ready-to-run install line), plus a top-level+   `_skillsHint`.++So an AI in any container can ask your desktop what it has, and get back the literal+command that fixes its own missing documentation. It never has to guess a package name.++A `skillPkg` of null means there is nothing separate to install: the skill is already part+of the Adom Bridge core package, or the bridge does not ship one.++## The one command, and the self-healing++```bash+adom-bridge-cli sync_skills+```++That collects every non-null `skillPkg` from every connected desktop and installs each+one. It is idempotent, so running it again costs nothing. It fans out across multiple+desktops and takes the union, so a container talking to two machines gets the skills for+both.++You do not normally have to run it. The CLI runs it opportunistically in the background,+at most once a day. That runs in containers only (the desktop host itself is skipped), and+`ADOM_SKILL_SYNC=0` opts out.++The daily run is what makes the awkward case work. A container that connects a week after+you installed a bridge, and that never asked your desktop to install anything, still ends+up with the right documentation, hands-off.++## Why bridge skills are not in Adom Bridge's own package++The cloud-owned bridges (KiCad, Fusion, Blender, Puppeteer, the browser extension) each+own their wiki page and their own skill package. Their docs are not bundled into the+adom-bridge core package, and that is deliberate.++Bundling would mean the docs go stale the moment a bridge ships an update, and it would+mean cutting an Adom Bridge release every time someone else's project changed a+paragraph. Each bridge ships its own skills on its own cadence, which is the only+arrangement that keeps a fast-moving bridge's documentation accurate.++## What does not belong in the skills tarball++The skills package is text and nothing else. Specifically, it should not contain:++- **Hero images or screenshots.** A container never renders them. One real bridge shipped+  a 1 MB hero in its tarball, which was pure download bloat on every single install.+- **The release zip.** That is the other artifact, and it goes to the desktop.+- **The source tree or any binaries.** A consumer container does not build the bridge.+- **Dev skills and publish skills.** Dev skills are for whoever edits the bridge, publish+  skills are for whoever releases it. Both stay in the source repo, where a developer who+  checks out the code gets them automatically. A consumer container has no use for either.++Only user skills ship. If you are looking at a bridge's tarball and it is measured in+megabytes, something is in there that should not be.++## What this looks like when it works++You install a bridge on your desktop, from the Bridges sidebar or with `bridge_install`.+The card appears, and the bridge is ready to run.++The AI in your container asks the desktop what is available. It gets back the bridge, and+alongside it, the install line for that bridge's skills. It runs that line. The skills+land in its own skills folder.++From that point on it drives the bridge's verbs with real documentation in front of it,+instead of guessing at argument names and reading error messages to find out what it got+wrong.++One thing to expect: the runtime on your desktop and the docs in your container can+legitimately sit at different versions, because they update on independent schedules. The+desktop's copy refreshes from the bridge's wiki page on a periodic sweep; the container's+copy refreshes when skills are synced. That is normal, and usually invisible.++## For bridge authors++If you are publishing a bridge rather than using one, the Bridge SDK on the+`adom-desktop-bridges` wiki page has the publishing detail: what belongs in each artifact,+how to declare `docs` so the skill package name resolves, and how to ship both halves+together.

@@ -1,134 +1,134 @@-# Bridges: the mini-apps that teach Adom Desktop new tricks
-
-Bridges are how Adom Desktop (AD) reaches beyond the operating system into specific
-apps. Each bridge is a small, independently-versioned process that AD spawns,
-supervises, health-checks, and auto-updates from its own wiki page. Every install ships
-with six of them:
-
-![Bridge cards in the sidebar with health LEDs](bridge-cards-pup-fusion.png)
-
-| Bridge | Verb prefix | What it does |
-|---|---|---|
-| Puppeteer | `browser_*` | A dedicated Chrome-for-Testing (or Edge) that AD downloads and manages: windows, tabs, page drive, JS eval, screenshots, recording. |
-| Native Browser | `nbrowser_*` | Your real, signed-in Chrome or Edge profile, for the logins and forms a throwaway automation profile cannot do. Works extension-free out of the box; the companion extension unlocks full in-page drive. |
-| KiCad | `kicad_*` | Schematic and PCB automation: DRC/ERC, gerber and STEP export, 3D render, netlist and footprint queries. |
-| Fusion 360 + APS | `fusion_*`, `aps_*` | Parametric modeling scripts and exports, plus fast indexed cloud-file search. |
-| Blender | `blender_*` | Headless Python scripting and renders. |
-| Hydrogen Desktop | `hd_*` | The local dev-environment app AD can embed into; AD relays its runtime state. |
-
-Third-party bridges install the same way and show up in the same place.
-
-## The Bridges sidebar
-
-The right side of the AD window is a full-height sidebar showing each installed bridge
-as a mini-app card:
-
-- A hero image (the bridge's own wiki billboard), the bridge name, a short description,
-  the author, and a star count.
-- A health LED with a short status label next to it.
-- Language and source badges (Python or Node; bundled, cache, or third-party).
-- A small `?` help icon. Hover it for the full tooltip: the bridge's own detailed status
-  text, its wiki page, and where its hero image came from.
-
-Click a card to open the wide pop-out console:
-
-- A live console: the bridge's own log plus the history of commands routed to it.
-- A ports and process debug view with live PIDs (more than one PID flags a runaway).
-- Every management action: install, uninstall, kill, restart, pause, resume, plus
-  "filter the activity log to this bridge" and "copy contribution prompt".
-
-The sidebar collapses to a thin rail if you want the space back. Two buttons live at the
-top: **+ Bridge** (install one by manifest URL) and **Check for updates**.
-
-## What the LED colors mean
-
-The bridge itself decides its color and status text; AD just paints what it reports,
-refreshing about every 15 seconds. The one exception is gray, which AD owns, because a
-dead bridge cannot report anything.
-
-| LED | Meaning | What to do |
-|---|---|---|
-| Green | Healthy. The bridge reported it is fine (or is reachable and did not say otherwise). | Nothing. |
-| Yellow | Degraded, per the bridge itself. For example, an upstream it depends on is partially down. | Hover the `?` for the bridge's own explanation. |
-| Red | The bridge knows it is broken. For example, it lost its connection to the app it drives. | Read the tooltip, then open the card's console for the live log. |
-| Gray | Off or unreachable. The bridge process is not running or its health endpoint is not answering. | Usually fine: bridges start on first use. A bridge marked persistent respawns by itself within seconds. |
-
-A gray dot on a bridge you have never used is normal. Bridges spawn on the first command
-of their prefix, not at AD startup, and a bridge whose host app (KiCad, Fusion) is not
-installed on this machine is deliberately left un-spawned.
-
-## How a bridge runs (the short version)
-
-- AD starts a bridge automatically on the first verb that targets it.
-- Each bridge keeps one stable port across restarts, so external clients (like the
-  browser extension) always find it in the same place.
-- AD enforces a single instance per bridge: duplicates are detected and reaped, and a
-  stale copy is cleaned up before a fresh one starts.
-- Bridges marked persistent are auto-respawned on death by a supervisor. Killing one to
-  pick up new code just brings it right back.
-
-## Installing a bridge
-
-From the GUI: click **+ Bridge** at the top of the sidebar and paste the bridge's
-manifest URL (published on its wiki page). From the command line:
-
-```bash
-adom-desktop bridge_install '{"manifestUrl":"https://wiki.adom.inc/api/v1/pages/<bridge-page>/files/<bridge>-bridge-manifest.json"}'
-```
-
-On success the card appears in the sidebar immediately. It sits gray until its first
-use, then goes green. On failure nothing is registered and no card appears; the error
-says why (most commonly the manifest's download URL could not be fetched).
-
-Uninstalling from the card's pop-out (or `bridge_uninstall`) removes a third-party
-bridge entirely; a bundled bridge reverts to the copy that shipped in the installer.
-
-## How updates arrive
-
-You normally do nothing. On launch and every 4 hours, AD checks each bridge's own wiki
-page for a newer version. When one exists, AD downloads it (checksum-verified) into a
-local cache, and the cached copy supersedes the bundled one. The bridge picks up the
-new code on its next natural respawn.
-
-On demand, the **Check for updates** button next to **+ Bridge** does the same sweep
-immediately, or:
-
-```bash
-adom-desktop bridge_check_updates          # read-only: what is behind, per bridge
-adom-desktop refresh_bridges               # update everything that is behind
-```
-
-Note that Puppeteer is bundled-only (its dependencies exceed the wiki file limit), so it
-updates with the AD installer itself rather than from a wiki page.
-
-## When something is wrong
-
-- **Gray and it should be running:** call any verb of its prefix, or open the card and
-  use Restart. Persistent bridges come back on their own.
-- **Red or yellow:** the tooltip is the bridge's own diagnosis; the card's live console
-  shows its log as it runs.
-- **A bridge keeps restarting:** the console tail includes AD's own lifecycle record,
-  which survives restarts. A line saying AD reaped the process means AD removed a
-  duplicate; a spawn line with no reap before it means the bridge exited on its own.
-- **A verb answers "paused":** someone paused routing to that bridge. Resume from the
-  card or with `bridge_resume`. Pausing never kills the process; it only makes the
-  bridge's verbs fail fast.
-
-## Where each bridge's real documentation lives
-
-This page covers the lifecycle: how bridges run, install, and update. How to actually
-USE a bridge (its verbs, workflows, and recipes) is documented by the bridge itself, on
-its own wiki page, which is also where its skill package for AI callers ships from:
-
-- Puppeteer: wiki.adom.inc, the `adom-desktop-puppeteer-bridge` page
-- KiCad: the `adom-desktop-kicad-bridge` page
-- Fusion 360: the `adom-desktop-fusion-bridge` page
-- Blender: the `adom-desktop-blender-bridge` page
-- Native Browser: the `adom-browser-extension` page
-
-Each card's wiki link takes you straight there. To build a bridge of your own, start
-with the Bridge SDK on the `adom-desktop-bridges` wiki page.
-
-## Private bridges
-
-A bridge on a private wiki page works like any other as long as Adom Desktop is signed in with an account that can see the page: installs and automatic updates send your signed-in token. Teams keep org-internal bridges private for exactly this reason. If an install reports that the page was not found, check the signed-in identity in the footer first.
+# Bridges: the mini-apps that teach Adom Bridge new tricks++Bridges are how Adom Bridge (Adom Bridge) reaches beyond the operating system into specific+apps. Each bridge is a small, independently-versioned process that Adom Bridge spawns,+supervises, health-checks, and auto-updates from its own wiki page. Every install ships+with six of them:++![Bridge cards in the sidebar with health LEDs](bridge-cards-pup-fusion.png)++| Bridge | Verb prefix | What it does |+|---|---|---|+| Puppeteer | `pup_*` | A dedicated Chrome-for-Testing (or Edge) that Adom Bridge downloads and manages: windows, tabs, page drive, JS eval, screenshots, recording. |+| Native Browser | `nbrowser_*` | Your real, signed-in Chrome or Edge profile, for the logins and forms a throwaway automation profile cannot do. Works extension-free out of the box; the companion extension unlocks full in-page drive. |+| KiCad | `kicad_*` | Schematic and PCB automation: DRC/ERC, gerber and STEP export, 3D render, netlist and footprint queries. |+| Fusion 360 + APS | `fusion_*`, `aps_*` | Parametric modeling scripts and exports, plus fast indexed cloud-file search. |+| Blender | `blender_*` | Headless Python scripting and renders. |+| Hydrogen | `hd_*` | The local dev-environment app Adom Bridge can embed into; Adom Bridge relays its runtime state. |++Third-party bridges install the same way and show up in the same place.++## The Bridges sidebar++The right side of the Adom Bridge window is a full-height sidebar showing each installed bridge+as a mini-app card:++- A hero image (the bridge's own wiki billboard), the bridge name, a short description,+  the author, and a star count.+- A health LED with a short status label next to it.+- Language and source badges (Python or Node; bundled, cache, or third-party).+- A small `?` help icon. Hover it for the full tooltip: the bridge's own detailed status+  text, its wiki page, and where its hero image came from.++Click a card to open the wide pop-out console:++- A live console: the bridge's own log plus the history of commands routed to it.+- A ports and process debug view with live PIDs (more than one PID flags a runaway).+- Every management action: install, uninstall, kill, restart, pause, resume, plus+  "filter the activity log to this bridge" and "copy contribution prompt".++The sidebar collapses to a thin rail if you want the space back. Two buttons live at the+top: **+ Bridge** (install one by manifest URL) and **Check for updates**.++## What the LED colors mean++The bridge itself decides its color and status text; Adom Bridge just paints what it reports,+refreshing about every 15 seconds. The one exception is gray, which Adom Bridge owns, because a+dead bridge cannot report anything.++| LED | Meaning | What to do |+|---|---|---|+| Green | Healthy. The bridge reported it is fine (or is reachable and did not say otherwise). | Nothing. |+| Yellow | Degraded, per the bridge itself. For example, an upstream it depends on is partially down. | Hover the `?` for the bridge's own explanation. |+| Red | The bridge knows it is broken. For example, it lost its connection to the app it drives. | Read the tooltip, then open the card's console for the live log. |+| Gray | Off or unreachable. The bridge process is not running or its health endpoint is not answering. | Usually fine: bridges start on first use. A bridge marked persistent respawns by itself within seconds. |++A gray dot on a bridge you have never used is normal. Bridges spawn on the first command+of their prefix, not at Adom Bridge startup, and a bridge whose host app (KiCad, Fusion) is not+installed on this machine is deliberately left un-spawned.++## How a bridge runs (the short version)++- Adom Bridge starts a bridge automatically on the first verb that targets it.+- Each bridge keeps one stable port across restarts, so external clients (like the+  browser extension) always find it in the same place.+- Adom Bridge enforces a single instance per bridge: duplicates are detected and reaped, and a+  stale copy is cleaned up before a fresh one starts.+- Bridges marked persistent are auto-respawned on death by a supervisor. Killing one to+  pick up new code just brings it right back.++## Installing a bridge++From the GUI: click **+ Bridge** at the top of the sidebar and paste the bridge's+manifest URL (published on its wiki page). From the command line:++```bash+adom-bridge-cli bridge_install '{"manifestUrl":"https://wiki.adom.inc/api/v1/pages/<bridge-page>/files/<bridge>-bridge-manifest.json"}'+```++On success the card appears in the sidebar immediately. It sits gray until its first+use, then goes green. On failure nothing is registered and no card appears; the error+says why (most commonly the manifest's download URL could not be fetched).++Uninstalling from the card's pop-out (or `bridge_uninstall`) removes a third-party+bridge entirely; a bundled bridge reverts to the copy that shipped in the installer.++## How updates arrive++You normally do nothing. On launch and every 4 hours, Adom Bridge checks each bridge's own wiki+page for a newer version. When one exists, Adom Bridge downloads it (checksum-verified) into a+local cache, and the cached copy supersedes the bundled one. The bridge picks up the+new code on its next natural respawn.++On demand, the **Check for updates** button next to **+ Bridge** does the same sweep+immediately, or:++```bash+adom-bridge-cli bridge_check_updates          # read-only: what is behind, per bridge+adom-bridge refresh_bridges               # update everything that is behind+```++Note that Puppeteer is bundled-only (its dependencies exceed the wiki file limit), so it+updates with the Adom Bridge installer itself rather than from a wiki page.++## When something is wrong++- **Gray and it should be running:** call any verb of its prefix, or open the card and+  use Restart. Persistent bridges come back on their own.+- **Red or yellow:** the tooltip is the bridge's own diagnosis; the card's live console+  shows its log as it runs.+- **A bridge keeps restarting:** the console tail includes Adom Bridge's own lifecycle record,+  which survives restarts. A line saying Adom Bridge reaped the process means Adom Bridge removed a+  duplicate; a spawn line with no reap before it means the bridge exited on its own.+- **A verb answers "paused":** someone paused routing to that bridge. Resume from the+  card or with `bridge_resume`. Pausing never kills the process; it only makes the+  bridge's verbs fail fast.++## Where each bridge's real documentation lives++This page covers the lifecycle: how bridges run, install, and update. How to actually+USE a bridge (its verbs, workflows, and recipes) is documented by the bridge itself, on+its own wiki page, which is also where its skill package for AI callers ships from:++- Puppeteer: wiki.adom.inc, the `adom-desktop-puppeteer-bridge` page+- KiCad: the `adom-desktop-kicad-bridge` page+- Fusion 360: the `adom-desktop-fusion-bridge` page+- Blender: the `adom-desktop-blender-bridge` page+- Native Browser: the `adom-browser-extension` page++Each card's wiki link takes you straight there. To build a bridge of your own, start+with the Bridge SDK on the `adom-desktop-bridges` wiki page.++## Private bridges++A bridge on a private wiki page works like any other as long as Adom Bridge is signed in with an account that can see the page: installs and automatic updates send your signed-in token. Teams keep org-internal bridges private for exactly this reason. If an install reports that the page was not found, check the signed-in identity in the footer first.

@@ -1,6 +1,6 @@ # Caller identity: knowing which AI tab is driving your machine -If you use Adom Desktop the way most people do, you have something like twenty AI+If you use Adom Bridge the way most people do, you have something like twenty AI conversation tabs open at once, all pointed at the same PC. One is fetching parts, one is reviewing a board, one is cleaning up a downloads folder, and several are idle. @@ -8,8 +8,7 @@ Until now they all looked the same. An approval toast said an AI wanted to run a command, and the Activity Log was one undifferentiated stream. If a tab went off the rails, there was no way to tell which one. -As of v1.9.180, every command that reaches your desktop over the relay has to say who is-asking.+As of v1.9.180, every command that reaches your desktop has to say who is asking.  ## What you get @@ -37,11 +36,11 @@ thought it was doing. ## In the approval toast  Windows notifications have a dedicated attribution slot: a separated, greyed line under-the main content. Adom Desktop puts the thread and container there, so the toast reads+the main content. Adom Bridge puts the thread and container there, so the toast reads roughly like this:  ```-  Adom Desktop: approval needed+  Adom Bridge: approval needed    run_script wants to run a bash script.   The AI says: checking whether the gerber zip finished downloading@@ -65,11 +64,11 @@ This is worth understanding clearly.  The **thread name is chosen by the AI itself**. When you read a name on an approval prompt or in the Activity Log, that name was written by the AI, not established by Adom-Desktop. Adom Desktop records it and displays it, but it cannot verify it. It is a+Desktop. Adom Bridge records it and displays it, but it cannot verify it. It is a label, not a credential. Nothing in the system grants or denies permission based on a thread name, and you should not treat one as proof of anything. -The **container name is different**. Adom Desktop knows the verified container from the+The **container name is different**. Adom Bridge knows the verified container from the authenticated relay connection, independently of anything the AI claims. When the self-reported container and the verified one disagree, both are shown so the discrepancy is visible rather than silently resolved.@@ -81,7 +80,7 @@ own tabs in your own containers, and the problem being solved is telling them ap  ## Bridges can use it too -Adom Desktop passes the caller information along to bridges (the components that drive+Adom Bridge passes the caller information along to bridges (the components that drive KiCad, Fusion, a browser, and so on) with every request it relays. A bridge can use that to log activity per thread, to label a window it opens with the conversation that owns it, or to arbitrate when two threads want the same resource at the same time.@@ -89,6 +88,47 @@ it, or to arbitrate when two threads want the same resource at the same time. So over time you should expect the "which tab did this?" answer to show up in more places than just the Activity Log and the toast. +## When a bridge does the work for a tab (v1.9.183)++Bridges do not only receive instructions, they turn around and ask Adom Bridge to do+things: take a screenshot of a window, relabel a taskbar button, send you a+notification. That last hop used to lose the trail. The tab's name reached the bridge,+and then disappeared: the Activity Log credited the bridge, and if the work needed your+approval, the toast asked you to authorize a nameless component with no mention of which+of your conversations had set it in motion.++As of v1.9.183 the name survives the whole way, and you see both parties:++```+chip-fetcher tab 3 (via pup)+```++That reads as "the pup bridge did this, because the chip-fetcher tab 3 conversation+asked it to". Showing only the tab would hide who actually ran the command; showing only+the bridge would hide who wanted it. Neither answer on its own is the one you need when+you are deciding whether to approve something, so you get both.++If a bridge does not identify itself by name, the line falls back to a generic "via+bridge". And if the work is genuinely the bridge's own idea (a health check, a scheduled+cleanup), the bridge reports itself rather than borrowing a conversation's name, so those+entries are not misattributed to a tab that was idle at the time.++The same caveat as before applies to all of it: the bridge name is self-reported too. It+is there so you can read the story of what happened, not to grant anyone permission.++## Hydrogen plays by the same rules++Hydrogen runs on your machine, but when it asks Adom Bridge to do something it+is doing so because an AI conversation inside it wants something. That is the same+situation as a cloud tab, so it has to say who is asking, exactly like everyone else.+Running locally is not a reason to be anonymous.++This matters more as Hydrogen grows to host several containers at once: it will+name both the container and the conversation that originated the request. There is one+mechanism for this across the whole system rather than a special case for each component,+which is why the "who asked, and who carried it out" line looks the same no matter where+the work came from.+ ## One place it changes behaviour  Killing a bridge affects every conversation using it, so it now gets a small guard. If@@ -106,10 +146,11 @@ Nothing you need to manage, but useful to recognise if you are reading along.  A conversation names itself on each command it sends, either with a command line flag (`--ai-thread "chip-fetcher tab 3"`) or by including the name in the command's own-arguments. If it sends nothing, the first relayed command is refused with a message-explaining exactly what to supply. Local callers are exempt, because they are already-trusted by how they connect: Hydrogen Desktop, a bridge calling back into Adom Desktop,-and the command line tool running on your own machine.+arguments. If it sends nothing, the first command is refused with a message explaining+exactly what to supply. Being on your own machine is not an exemption: Hydrogen+and the local command line tool have to identify themselves too. A bridge calling back+into Adom Bridge is the one remaining exception, and only while the bridges finish+adopting the pass-through described above.  Naming per command is what keeps those names honest. Your twenty tabs typically share one cloud container and one home directory, so anything set once for the whole

@@ -1,114 +1,114 @@-# The adom-desktop CLI
-
-The `adom-desktop` CLI is the caller surface for Adom Desktop. The GUI app runs on your
-Windows machine and does the work; the CLI is how anything else (a cloud AI in a Linux
-container, a local script, you at a terminal) asks it to do that work.
-
-![The Adom Desktop window the CLI drives](main-view.png)
-
-## Where it comes from
-
-There are two homes for the same CLI:
-
-- **Cloud Linux container**: installed by the package, `adom-wiki pkg install
-  adom/adom-desktop`, which lays down the `adom-desktop` binary and the Claude skill
-  set. The container also runs the relay server the desktop connects to.
-- **Windows, next to the GUI**: the Adom Desktop installer bundles
-  `adom-desktop-cli.exe` into `%LOCALAPPDATA%\Adom Desktop\` and adds that directory to
-  your PATH (per-user, no UAC). It finds the local GUI automatically over the loopback
-  direct API, so it works from any fresh terminal with no relay running.
-
-## The mental model
-
-Almost nothing in the CLI is a traditional subcommand. You invoke a verb by name with a
-JSON argument, and the CLI forwards it to the desktop app:
-
-```bash
-adom-desktop <verb> '<json-args>'
-```
-
-From a container the verb travels over the relay (a WebSocket hub the desktop dials out
-to). On Windows with no target specified, it goes straight to the local GUI. Either way
-the desktop executes it and you get back identical JSON: the same `status`
-(`ok` | `timeout` | `busy` | `error`), `durationMs`, `_hint`, and error fields on every
-path, so code written against one path works on all of them.
-
-Note that `adom-desktop --help` only lists the `serve` and `install` subcommands. The
-real functionality is the dynamic verb catalog, discovered at runtime (see the last
-section).
-
-## Cookbook
-
-Is the desktop reachable?
-
-```bash
-adom-desktop ping
-# { "echo": "pong", "roundTripMs": ..., "status": "connected" }
-```
-
-Which desktops are connected, and how do I address one? (With several desktops on one
-relay, a call without `--target` fails as ambiguous rather than guessing.)
-
-```bash
-adom-desktop targets
-adom-desktop --target azurevm desktop_screenshot_screen
-adom-desktop --target all hd_status
-```
-
-Take a screenshot of one window (the PNG is pulled to a local cache and the path
-returned):
-
-```bash
-adom-desktop desktop_list_windows
-adom-desktop desktop_screenshot_window '{"hwnd": 12345}'
-```
-
-Run a shell command on the desktop. This requires user approval when called over the
-relay, and the `reason` is shown verbatim in the approval prompt:
-
-```bash
-adom-desktop shell_execute '{"command":"echo hello","reason":"verifying the shell path works"}'
-```
-
-Send the user a desktop notification:
-
-```bash
-adom-desktop notify_user '{"title":"Build done","body":"The nightly build finished."}'
-```
-
-Move files between the container and the desktop:
-
-```bash
-adom-desktop send_files '{"files":["/tmp/report.pdf"],"saveTo":"C:/Users/john/Downloads"}'
-adom-desktop pull_file '{"filePaths":["C:/Users/john/Downloads/image.png"],"saveTo":"/tmp"}'
-```
-
-Start the relay in a container. Use `--supervise`: a plain backgrounded `serve &` dies
-when your session is torn down and leaves every connected desktop stuck reconnecting.
-The supervised relay detaches, restarts itself with backoff, and notifies the connected
-desktops when it does:
-
-```bash
-adom-desktop serve --supervise
-adom-desktop serve --stop
-```
-
-Check the relay is up:
-
-```bash
-curl -sf http://127.0.0.1:8766/health
-```
-
-## Learning every verb
-
-The complete, always-current catalog lives in the tool itself:
-
-```bash
-adom-desktop commands            # every verb: args, returns, prerequisites, hints
-adom-desktop help <topic>        # one verb or namespace, e.g. help shell, help pup
-```
-
-Run `commands` before reaching for `shell_execute`; most operations have a structured
-verb with typed arguments (process control, file watching, window management, WSL,
-tunnels) that needs no shell quoting at all. The full grouped reference is also in
-[VERBS.md](../VERBS.md).
+# The adom-bridge CLI++The `adom-bridge` CLI is the caller surface for Adom Bridge. The GUI app runs on your+Windows machine and does the work; the CLI is how anything else (a cloud AI in a Linux+container, a local script, you at a terminal) asks it to do that work.++![The Adom Bridge window the CLI drives](main-view.png)++## Where it comes from++There are two homes for the same CLI:++- **Cloud Linux container**: installed by the package, `adom-wiki pkg install+  adom/adom-desktop`, which lays down the `adom-bridge` binary and the Claude skill+  set. The container also runs the relay server the desktop connects to.+- **Windows, next to the GUI**: the Adom Bridge installer bundles+  `adom-bridge-cli.exe` into `%LOCALAPPDATA%\Adom Bridge\` and adds that directory to+  your PATH (per-user, no UAC). It finds the local GUI automatically over the loopback+  direct API, so it works from any fresh terminal with no relay running.++## The mental model++Almost nothing in the CLI is a traditional subcommand. You invoke a verb by name with a+JSON argument, and the CLI forwards it to the desktop app:++```bash+adom-bridge <verb> '<json-args>'+```++From a container the verb travels over the relay (a WebSocket hub the desktop dials out+to). On Windows with no target specified, it goes straight to the local GUI. Either way+the desktop executes it and you get back identical JSON: the same `status`+(`ok` | `timeout` | `busy` | `error`), `durationMs`, `_hint`, and error fields on every+path, so code written against one path works on all of them.++Note that `adom-bridge-cli --help` only lists the `serve` and `install` subcommands. The+real functionality is the dynamic verb catalog, discovered at runtime (see the last+section).++## Cookbook++Is the desktop reachable?++```bash+adom-bridge-cli ping+# { "echo": "pong", "roundTripMs": ..., "status": "connected" }+```++Which desktops are connected, and how do I address one? (With several desktops on one+relay, a call without `--target` fails as ambiguous rather than guessing.)++```bash+adom-bridge-cli targets+adom-bridge-cli --target azurevm desktop_screenshot_screen+adom-bridge-cli --target all hd_status+```++Take a screenshot of one window (the PNG is pulled to a local cache and the path+returned):++```bash+adom-bridge-cli desktop_list_windows+adom-bridge-cli desktop_screenshot_window '{"hwnd": 12345}'+```++Run a shell command on the desktop. This requires user approval when called over the+relay, and the `reason` is shown verbatim in the approval prompt:++```bash+adom-bridge-cli shell_execute '{"command":"echo hello","reason":"verifying the shell path works"}'+```++Send the user a desktop notification:++```bash+adom-bridge-cli notify_user '{"title":"Build done","body":"The nightly build finished."}'+```++Move files between the container and the desktop:++```bash+adom-bridge-cli send_files '{"files":["/tmp/report.pdf"],"saveTo":"C:/Users/john/Downloads"}'+adom-bridge-cli pull_file '{"filePaths":["C:/Users/john/Downloads/image.png"],"saveTo":"/tmp"}'+```++Start the relay in a container. Use `--supervise`: a plain backgrounded `serve &` dies+when your session is torn down and leaves every connected desktop stuck reconnecting.+The supervised relay detaches, restarts itself with backoff, and notifies the connected+desktops when it does:++```bash+adom-bridge-cli serve --supervise+adom-bridge-cli serve --stop+```++Check the relay is up:++```bash+curl -sf http://127.0.0.1:8766/health+```++## Learning every verb++The complete, always-current catalog lives in the tool itself:++```bash+adom-bridge-cli commands            # every verb: args, returns, prerequisites, hints+adom-bridge-cli help <topic>        # one verb or namespace, e.g. help shell, help pup+```++Run `commands` before reaching for `shell_execute`; most operations have a structured+verb with typed arguments (process control, file watching, window management, WSL,+tunnels) that needs no shell quoting at all. The full grouped reference is also in+[VERBS.md](../VERBS.md).

@@ -0,0 +1,103 @@+# Adom Bridge and Hydrogen++Adom Bridge (Adom Bridge) is a full product on its own: a standalone tray app that lets+AI assistants and remote sessions drive your Windows machine. Hydrogen+(Hydrogen) is a sibling app that bundles Adom Bridge 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 Adom Bridge++Hydrogen's installer carries the signed Adom Bridge installer and silent-installs it to the+normal location (`%LOCALAPPDATA%\Adom Bridge`). At runtime Hydrogen launches Adom Bridge 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 Adom Bridge works quietly underneath it.++Adom Bridge 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 Adom Bridge window or tray icon.** Adom Bridge hides both so that Hydrogen reads as+  the one app. Adom Bridge is still running and serving.+- **The taskbar tile changes.** Adom Bridge's window identity flips from the muted+  "Adom Bridge" tile to a vivid teal tile named "Adom Bridge Hydrogen Embedded".+  The swap happens in about a second, with no restart. The tile is the+  at-a-glance signal of which mode Adom Bridge is in.+- **A locked connection row.** In Adom Bridge'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. Adom Bridge'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+  Adom Bridge and goes away when Adom Bridge returns to standalone.++## When Hydrogen closes or crashes++Adom Bridge is designed to stay up. This is deliberate: Adom Bridge is the recovery channel for+the machine it runs on. As long as Adom Bridge is alive, a remote agent can read a log,+check what is installed, relaunch something, or roll back a bad update. If Adom Bridge+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 Adom Bridge it is releasing it, and Adom Bridge reverts to+  standalone on the spot: the tray icon comes back, the taskbar tile returns+  to the muted standalone look, and Adom Bridge's relay connections are preserved.+- **Hydrogen crashes or is killed.** Adom Bridge 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 Adom Bridge is an explicit shutdown**: the+  `desktop_shutdown` command, or you closing Adom Bridge yourself. There is a launch+  flag (`--exit-when-hd-exits`) that would make Adom Bridge exit alongside Hydrogen, but Hydrogen+  does not pass it, and there is no setting for it. In practice Adom Bridge always+  survives its parent.++One caveat: because Adom Bridge runs as Hydrogen's child process, an operating-system level+"kill the whole process tree" takes Adom Bridge down with Hydrogen instantly. That is the OS+at work, not Adom Bridge's behavior, and it is rare in normal use.++## Updates while embedded++Adom Bridge updates itself even when embedded, but the timing is shared:++- **Adom Bridge stages.** Adom Bridge 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 Adom Bridge to apply the staged+  update. Embedded Adom Bridge never restarts itself for an ordinary update; Hydrogen owns+  the restart timing so it does not interrupt your work.++When Adom Bridge 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 Adom Bridge 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 Adom Bridge at startup whether commands should be auto-approved. Unless you+  have opted in to auto-approval, Adom Bridge forwards each sensitive request to Hydrogen,+  and Hydrogen shows the approval prompt. Adom Bridge 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 Adom Bridge exactly as decided.+- If Hydrogen is ever unreachable at the moment of a request, Adom Bridge 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 Adom Bridge. Installed on its own, Adom Bridge 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 Adom Bridge can do.

@@ -1,106 +1,106 @@-# Using Adom Desktop from a local AI (Claude Desktop, Claude Code, Codex)
-
-You do not need the cloud to use Adom Desktop. Install AD on your PC, and any
-AI tool running on that same PC can immediately drive your machine: take
-screenshots, list and capture windows, launch apps, show you notifications,
-run commands. No relay, no container, no account wiring on the AI side.
-
-![Adom Desktop running on the PC](main-view.png)
-
-This page covers the local path. Driving your desktop from a cloud container
-over the relay is a separate setup, documented in the main README and the
-`adom-desktop` skill.
-
-## What the installer sets up
-
-When you run the signed Windows installer:
-
-- The GUI installs to `%LOCALAPPDATA%\Adom Desktop\` and starts on login.
-- A command-line tool, `adom-desktop-cli.exe`, is installed next to the GUI,
-  and that folder is added to your user PATH. Any local program can call it
-  by name from a fresh shell.
-- AD's consumer skills (the documentation an AI agent reads to learn the
-  verbs) are linked into your agents automatically. On every launch, AD
-  copies its bundled skills into both `~/.claude/skills/` (Claude Desktop and
-  Claude Code) and `~/.codex/skills/` (Codex).
-
-So the moment AD is installed and running, a local Claude or Codex session
-already knows what AD can do and how to call it.
-
-## How the skill auto-link works
-
-Each skill AD installs lives in its own folder, for example
-`~/.claude/skills/adom-desktop/`, and contains a small marker file named
-`.adom-managed`. The marker means "Adom Desktop owns this folder":
-
-- On every AD launch, each managed skill is refreshed if the bundled copy
-  changed (which happens when AD upgrades itself). Unchanged skills are left
-  alone, so a normal launch writes nothing.
-- If you made your own skill with the same folder name, AD sees there is no
-  marker and never touches it.
-- Deleting the `.adom-managed` marker from a folder stops AD from updating
-  that skill. Your edits to it become permanent.
-- To turn the whole feature off, launch AD with the environment variable
-  `ADOM_SKILLS_LINK=0`.
-
-## A worked example
-
-Say you are in Claude Code on your PC and you ask:
-
-> "Grab a screenshot of my Notepad window and let me know when it's saved."
-
-The agent, having the AD skills, would run something like:
-
-```
-adom-desktop-cli.exe desktop_list_windows
-adom-desktop-cli.exe desktop_screenshot_window '{"titleContains": "Notepad"}'
-adom-desktop-cli.exe notify_user '{"title":"Done","body":"Notepad screenshot saved"}'
-```
-
-The first call finds the window, the second captures it as a lossless PNG
-(window chrome included), and the third pops a Windows toast so you see the
-result even if the agent's console is buried. Every call goes straight to the
-running AD GUI over loopback (`127.0.0.1`); nothing leaves your machine.
-
-To see everything available:
-
-```
-adom-desktop-cli.exe commands
-```
-
-## Troubleshooting
-
-**Is AD running?** Look for the Adom Desktop tray icon, or open the window
-from the Start Menu. The window title shows the running version. If AD is
-closed to the tray it is still serving; closing the window does not stop it.
-
-**Quick liveness check:**
-
-```
-adom-desktop-cli.exe ping
-```
-
-A healthy AD answers immediately. If ping fails, launch Adom Desktop from
-the Start Menu and try again.
-
-**`adom-desktop-cli.exe` is not recognized.** The installer adds
-`%LOCALAPPDATA%\Adom Desktop\` to your PATH, but shells that were already
-open before the install do not see the change. Open a new terminal, or call
-it by full path:
-
-```
-"%LOCALAPPDATA%\Adom Desktop\adom-desktop-cli.exe" ping
-```
-
-**The skills did not appear in my agent.** They are linked when AD launches,
-so start (or restart) Adom Desktop, then check for folders like
-`~/.claude/skills/adom-desktop/`. If you set `ADOM_SKILLS_LINK=0`, the link
-is disabled.
-
-## Related docs
-
-- `skills/LOCAL_AI.md`: the agent-facing version of this page.
-- `skills/DIRECT_API.md`: the loopback HTTP API, for apps that want to call
-  AD without spawning the CLI.
-- `README.md`, "How it works" and "Install": the full picture, including the
-  cloud-relay path.
+# Using Adom Bridge from a local AI (Claude Desktop, Claude Code, Codex)++You do not need the cloud to use Adom Bridge. Install Adom Bridge on your PC, and any+AI tool running on that same PC can immediately drive your machine: take+screenshots, list and capture windows, launch apps, show you notifications,+run commands. No relay, no container, no account wiring on the AI side.++![Adom Bridge running on the PC](main-view.png)++This page covers the local path. Driving your desktop from a cloud container+over the relay is a separate setup, documented in the main README and the+`adom-bridge` skill.++## What the installer sets up++When you run the signed Windows installer:++- The GUI installs to `%LOCALAPPDATA%\Adom Bridge\` and starts on login.+- A command-line tool, `adom-bridge-cli.exe`, is installed next to the GUI,+  and that folder is added to your user PATH. Any local program can call it+  by name from a fresh shell.+- Adom Bridge's consumer skills (the documentation an AI agent reads to learn the+  verbs) are linked into your agents automatically. On every launch, Adom Bridge+  copies its bundled skills into both `~/.claude/skills/` (Claude Desktop and+  Claude Code) and `~/.codex/skills/` (Codex).++So the moment Adom Bridge is installed and running, a local Claude or Codex session+already knows what Adom Bridge can do and how to call it.++## How the skill auto-link works++Each skill Adom Bridge installs lives in its own folder, for example+`~/.claude/skills/adom-desktop/`, and contains a small marker file named+`.adom-managed`. The marker means "Adom Bridge owns this folder":++- On every Adom Bridge launch, each managed skill is refreshed if the bundled copy+  changed (which happens when Adom Bridge upgrades itself). Unchanged skills are left+  alone, so a normal launch writes nothing.+- If you made your own skill with the same folder name, Adom Bridge sees there is no+  marker and never touches it.+- Deleting the `.adom-managed` marker from a folder stops Adom Bridge from updating+  that skill. Your edits to it become permanent.+- To turn the whole feature off, launch Adom Bridge with the environment variable+  `ADOM_SKILLS_LINK=0`.++## A worked example++Say you are in Claude Code on your PC and you ask:++> "Grab a screenshot of my Notepad window and let me know when it's saved."++The agent, having the Adom Bridge skills, would run something like:++```+adom-bridge-cli.exe desktop_list_windows+adom-bridge-cli.exe desktop_screenshot_window '{"titleContains": "Notepad"}'+adom-bridge-cli.exe notify_user '{"title":"Done","body":"Notepad screenshot saved"}'+```++The first call finds the window, the second captures it as a lossless PNG+(window chrome included), and the third pops a Windows toast so you see the+result even if the agent's console is buried. Every call goes straight to the+running Adom Bridge GUI over loopback (`127.0.0.1`); nothing leaves your machine.++To see everything available:++```+adom-bridge-cli.exe commands+```++## Troubleshooting++**Is Adom Bridge running?** Look for the Adom Bridge tray icon, or open the window+from the Start Menu. The window title shows the running version. If Adom Bridge is+closed to the tray it is still serving; closing the window does not stop it.++**Quick liveness check:**++```+adom-bridge-cli.exe ping+```++A healthy Adom Bridge answers immediately. If ping fails, launch Adom Bridge from+the Start Menu and try again.++**`adom-bridge-cli.exe` is not recognized.** The installer adds+`%LOCALAPPDATA%\Adom Bridge\` to your PATH, but shells that were already+open before the install do not see the change. Open a new terminal, or call+it by full path:++```+"%LOCALAPPDATA%\Adom Bridge\adom-bridge-cli.exe" ping+```++**The skills did not appear in my agent.** They are linked when Adom Bridge launches,+so start (or restart) Adom Bridge, then check for folders like+`~/.claude/skills/adom-desktop/`. If you set `ADOM_SKILLS_LINK=0`, the link+is disabled.++## Related docs++- `skills/LOCAL_AI.md`: the agent-facing version of this page.+- `skills/DIRECT_API.md`: the loopback HTTP API, for apps that want to call+  Adom Bridge without spawning the CLI.+- `README.md`, "How it works" and "Install": the full picture, including the+  cloud-relay path.

@@ -1,61 +1,104 @@-# Permissions: how Adom Desktop asks you before an AI acts
-
-Adom Desktop lets a cloud AI drive your machine. That is the point of the app, but some actions deserve a checkpoint: anything that runs code, writes or deletes files, edits the registry, kills processes, or types and clicks as you. When a remote AI asks for one of those, Adom Desktop stops and asks you first.
-
-![The shell approval toast with Approve 1 hr, 24 hr and Bypass buttons](approve-bar.png)
-
-The principle behind all of it: **the AI can ASK for permission, but only you can GRANT it.** There is no way for the AI to approve itself. It can pop the prompt in front of you, and that is all.
-
-## What you will see
-
-When a remote AI hits the gate, three things happen at once:
-
-1. **An approval dialog inside the Adom Desktop window.** It shows what the AI wants to run (the actual command or file path, not just a verb name) and the buttons Approve 1 hr, Approve 24 hr, and Bypass Permissions.
-2. **A Windows toast notification** with the same Approve buttons. You can grant straight from the toast without opening the window.
-3. **The taskbar icon flashes** so you notice even if the window is buried.
-
-If you missed it, the AI can re-surface the same prompt and bring the window to the front. Nothing runs until you decide.
-
-When Adom Desktop is running inside Hydrogen Desktop, the prompt appears in Hydrogen Desktop instead (it owns the screen in that mode). The choices mean the same things.
-
-## What each choice means
-
-- **Approve once** (in Hydrogen Desktop's prompt): run this one command only. The very next command asks again.
-- **Approve 1 hr / Approve 24 hr**: auto-approve this class of actions for a timed window, so a working session is not interrupted on every command. When the timer expires, prompting resumes on its own.
-- **Bypass Permissions**: auto-approve indefinitely. This is for machines you fully trust the AI on, such as a dedicated work box. It stays on until you turn it off. The same switch lives in Settings, under Shell Commands, as the Bypass Permissions checkbox.
-- **Deny** (in Hydrogen Desktop's prompt): refuse the command. The AI is told you said no and that it should not silently retry.
-
-One grant covers the whole class of gated actions (run code, write files, registry, kill processes, synthetic input). You are not approving a single verb, you are opening a window of trust.
-
-## Why the AI must state a reason, and why you should read it
-
-Every gated request carries a line from the AI, shown as:
-
-> The AI says: "Installing the KiCad CLI so I can export your gerbers"
-
-The AI is required to explain WHY it wants the action, in one plain sentence. A request without one shows "(no reason given)", and a cautious user should decline it: an AI that read the documentation always supplies a reason.
-
-Read the reason, but do not treat it as proof. It is text written by the requester, and the gate exists precisely because that requester might be wrong or manipulated. A persuasive reason is exactly what a compromised agent would write. That is why the prompt always shows the actual command alongside the reason: the command is the ground truth, the reason is context. If the reason and the command do not match, decline.
-
-## How to revoke
-
-Any grant can be dropped instantly, at any time:
-
-- **In the app:** Settings, then Shell Commands, then untick Bypass Permissions. This clears the durable grant and any running timer.
-- **From a command line:**
-
-  ```bash
-  adom-desktop shell_auto_approve '{"duration_secs":0}'
-  ```
-
-  Revoking is always allowed, from anywhere, for anyone (including the AI itself). Only granting is restricted to you.
-
-After a revoke, the very next gated command prompts again.
-
-## What is never gated
-
-Read-only actions (screenshots, window lists, status checks, reading UI text) run without prompting. So do commands from software already on your own machine: your local command line, Hydrogen Desktop, and installed bridges are trusted because installing them was your decision, and Adom Desktop only listens on localhost, so nothing can reach it over the network. The gate is specifically for the remote cloud AI, the one origin that acts on your machine while you may not be watching.
-
-## The rule to remember
-
-The prompt is the boundary. The AI can knock as loudly as it likes: pop the dialog, fire the toast, flash the taskbar. But the Approve button only works when a human clicks it, and every grant you give can be taken back in one click.
+# Permissions: how Adom Bridge asks you before an AI acts++Adom Bridge lets a cloud AI drive your machine. That is the point of the app, but some actions deserve a checkpoint: anything that runs code, writes or deletes files, edits the registry, kills processes, or types and clicks as you. When a remote AI asks for one of those, Adom Bridge stops and asks you first.++![The Adom Bridge shell approval dialog: the command, the AI's stated reason, and the Approve once / 1 hr / 24 hr / Bypass / Deny buttons](approval-dialog.png)++The principle behind all of it: **the AI can ASK for permission, but only you can GRANT it.** There is no way for the AI to approve itself. It can pop the prompt in front of you, and that is all. Adom Bridge owns every approval decision, in every mode. Nothing else on your machine can grant on your behalf.++## The approval dialog inside the Adom Bridge window++When a remote AI hits the gate, an approval dialog opens inside the Adom Bridge window. It shows the real request, not just a verb name:++- The actual command or file path the AI wants to run.+- The AI's stated reason (see below).+- The working directory the command would run in.++The dialog has five buttons: **Approve once**, **Approve 1 hr**, **Approve 24 hr**, **Bypass Permissions**, and **Deny**. Each button has a hover tooltip, so if you are unsure what one does, rest your pointer on it and a short explanation appears. Nothing runs until you click one.++Alongside the dialog, the taskbar icon flashes so you notice even if the window is buried. If you missed the prompt entirely, the AI can re-surface it and bring the window to the front, but it still cannot decide for you.++## What each button means++- **Approve once**: run this one command only. The very next gated command asks again.+- **Approve 1 hr / Approve 24 hr**: auto-approve the whole gated class for a timed window, so a working session is not interrupted on every command. When the timer expires, prompting resumes on its own.+- **Bypass Permissions**: auto-approve indefinitely, until you turn it off. This is the durable preference, for machines you fully trust the AI on, such as a dedicated work box. The same switch lives in Settings, under Shell Commands, as the Bypass Permissions checkbox.+- **Deny**: refuse this command. The AI is told you said no, and that it should not silently retry.++There is exactly one Bypass button. One grant covers the whole class of gated actions (run code, write files, edit registry, kill processes, synthetic input). You are not approving a single verb, you are opening a window of trust: once for a single command, timed for a session, or durable until revoked.++## The Windows toast++At the same time as the dialog, Adom Bridge fires a Windows toast notification so you can decide without opening the window. The toast is branded **Adom Bridge**, so you always know which app is asking.++Its buttons carry short labels: **Once**, **1 hour**, **24 hours**, **Bypass**, and **Deny**. They mean the same things as the dialog buttons above. The labels are kept short on purpose, because Windows clips long toast button text and offers no place for a hover tooltip (that is why the in-window dialog is where the fuller wording and tooltips live).++Clicking an approve button on the toast resolves the request but does **not** drag the Adom Bridge window to the foreground. You granted from the toast precisely so you would not have to switch away from whatever you were doing, so Adom Bridge stays out of your way.++The dialog, the toast, and (in embedded mode) Hydrogen's prompt are all surfaces for the same one request. The first click on any of them wins, and the others close on their own.++## Running inside Hydrogen (embedded mode)++When Adom Bridge runs embedded inside Hydrogen, approvals work exactly as they do standalone. Adom Bridge still owns the decision, and it still shows its own Adom-Desktop-branded dialog and toast.++In addition, Adom Bridge mirrors the request over to Hydrogen, which can raise its own Hydrogen-Desktop-branded prompt. So for a single request you may see two prompts: one from Adom Bridge, one from Hydrogen. That is intentional. Adom Bridge keeps its own prompt Adom-branded on purpose, so that even while embedded you learn that Adom Bridge is the app doing the work and the app that owns the gate.++Hydrogen stores no approval state of its own. It is only a display surface: your click there is handed straight back to Adom Bridge, which makes the actual decision. A decision on any surface resolves the request, and Adom Bridge then closes its own dialog and asks Hydrogen to close its prompt too, so you never have to dismiss two things.++Whether Adom Bridge is embedded is worked out live each time (Hydrogen present and reachable), never read from a stored setting that could go stale. Hydrogen cannot pre-authorize or force-approve anything. Silencing prompts is your call, made in Adom Bridge with Bypass.++That mirror only happens when Adom Bridge is actually going to ask you. If a grant is already active, Bypass Permissions or a running 1 hour or 24 hour window, Adom Bridge approves the command itself and shows no prompt, so it does not mirror anything to Hydrogen and no Hydrogen dialog appears either. In other words, a grant you gave in Adom Bridge silences both surfaces, not just Adom Bridge's own.++## Why the AI must state a reason, and why you should read it++Every gated request carries a line from the AI, shown as:++> The AI says: "Installing the KiCad CLI so I can export your gerbers"++The AI is required to explain WHY it wants the action, in one plain sentence. A request without one shows "(no reason given)", and a cautious user should decline it: an AI that read the documentation always supplies a reason.++Read the reason, but do not treat it as proof. It is text written by the requester, and the gate exists precisely because that requester might be wrong or manipulated. A persuasive reason is exactly what a compromised agent would write. That is why the prompt always shows the actual command alongside the reason: the command is the ground truth, the reason is context. If the reason and the command do not match, decline.++The request also shows who is asking (the AI thread and container), so if you run several AI threads against one machine you can see which one wants this. That identity is self-reported and shown for information only. It is never used to decide anything on its own.++## What survives a restart, and what does not++Grants live in two places. Most are in memory and vanish when Adom Bridge restarts. Only the Bypass preference is written to disk.++| Grant | Where it lives | Survives restart? |+| --- | --- | --- |+| Once / Deny | In memory, a single decision | No |+| Approve 1 hr / Approve 24 hr | In-memory timer | No |+| Bypass Permissions | On disk in config.json (`shell_auto_approve_permanent`) | Yes (the only durable grant) |++Once and Deny are single decisions and are never remembered. A 1 hour or 24 hour grant is a timer held in memory: it is session-scoped by design, so if Adom Bridge restarts the timed window is gone and prompting resumes. Bypass Permissions is a saved preference, the checkbox under Settings, Shell Commands, so it stays on across restarts until you turn it off. It is the only durable grant.++There is one deliberate exception, and it turns on how the restart happened, not who clicked. Any update that runs through Adom Bridge's own updater, whether it applied on its own overnight or you clicked Install now, hands the remaining timed window forward through a small handoff file that can be read once and expires after 120 seconds. A restart that does not go through the updater, an ordinary reboot, quitting the app, or running the installer .exe by hand, writes no handoff, so the timed window is gone as usual. The point is narrow: updating Adom Bridge should not silently revoke the hour you granted a moment earlier, but a plain restart still resets things, which is what you would expect.++| How the restart happened | Timed 1 hr / 24 hr window | Bypass |+| --- | --- | --- |+| Update through Adom Bridge (auto, or Install now) | Carries across | Survives |+| Reboot, quit, or running the installer .exe yourself | Gone | Survives |++## How to revoke++Any grant can be dropped instantly, at any time:++- **In the app:** Settings, then Shell Commands, then untick Bypass Permissions. This clears the durable grant and any running timer.+- **From a command line:**++  ```bash+  adom-bridge shell_auto_approve '{"duration_secs":0}'+  ```++  Revoking is always allowed, from anywhere, for anyone (including the AI itself). Only granting is restricted to you.++After a revoke, the very next gated command prompts again.++## What is never gated++Read-only actions (screenshots, window lists, status checks, reading UI text) run without prompting. So do commands from software already on your own machine: your local command line, Hydrogen, and installed bridges are trusted because installing them was your decision, and Adom Bridge only listens on localhost, so nothing can reach it over the network. The gate is specifically for the remote cloud AI, the one origin that acts on your machine while you may not be watching.++## The rule to remember++The prompt is the boundary. The AI can knock as loudly as it likes: pop the dialog, fire the toast, flash the taskbar. But the Approve button only works when a human clicks it, and every grant you give can be taken back in one click.

@@ -1,9 +1,9 @@-# Adom Desktop in the background: the tray, the hidden window, and the taskbar tile+# Adom Bridge in the background: the tray, the hidden window, and the taskbar tile -Adom Desktop is built to live quietly on your machine. Most of the time its+Adom Bridge is built to live quietly on your machine. Most of the time its window is hidden and it sits in the system tray, still connected and still serving, while costing very little. This page explains what closing the window-really does, why that is cheap, how to read AD's mode from the taskbar alone,+really does, why that is cheap, how to read Adom Bridge's mode from the taskbar alone, and how to actually exit.  ![The muted standalone taskbar tile](taskbar-standalone.png)@@ -11,22 +11,22 @@ and how to actually exit.  ## What closing the window really does -Clicking the X on AD's window hides the window. It does not exit the app. AD+Clicking the X on Adom Bridge's window hides the window. It does not exit the app. Adom Bridge keeps running in the background: it stays connected to your relay, keeps its bridges alive, and can still show notifications and approval prompts. That is the point of the app; it is the always-reachable agent surface for your machine, so "close" means "get out of my way", not "stop working". -You will not be left guessing. The first three times you close the window, AD+You will not be left guessing. The first three times you close the window, Adom Bridge shows a notification explaining that it moved to the tray. After that it assumes you know and stays quiet. -If you launch AD again while it is hidden, the existing instance simply shows+If you launch Adom Bridge again while it is hidden, the existing instance simply shows and focuses its window (there is never a second copy running). -## Why AD in the tray costs very little+## Why Adom Bridge in the tray costs very little -AD is two things: a small native core process that does all the real work+Adom Bridge is two things: a small native core process that does all the real work (roughly 60 MB), and a web-technology window (WebView2) that only exists to paint the user interface. @@ -45,13 +45,13 @@ window appearing.  ## Reading the mode from the taskbar tile -AD runs in one of two modes, and the taskbar button tells you which without+Adom Bridge runs in one of two modes, and the taskbar button tells you which without opening anything: -- A MUTED teal tile named "Adom Desktop": AD is running standalone, on its+- A MUTED teal tile named "Adom Bridge": Adom Bridge is running standalone, on its   own. This is the default for a normal install.-- A VIVID teal tile named "Adom Desktop Hydrogen Embedded": Hydrogen Desktop-  launched AD and is driving its lifecycle.+- A VIVID teal tile named "Adom Bridge Hydrogen Embedded": Hydrogen+  launched Adom Bridge and is driving its lifecycle.  The swap is live: when the mode changes, the button's tile and name change within about a second, with no restart and no flicker. Under the hood each@@ -60,10 +60,10 @@ between them.  Two things to know: -- A taskbar pin belongs to one identity. If you pin AD in one mode, the-  running window shows as a separate button whenever AD is in the other mode.-- The tray icon exists only in standalone mode. When AD is embedded in-  Hydrogen Desktop, the tray icon is hidden, so the taskbar tile is the way+- A taskbar pin belongs to one identity. If you pin Adom Bridge in one mode, the+  running window shows as a separate button whenever Adom Bridge is in the other mode.+- The tray icon exists only in standalone mode. When Adom Bridge is embedded in+  Hydrogen, the tray icon is hidden, so the taskbar tile is the way   to tell the modes apart.  The window title is also informative: it shows the running version, whether@@ -71,33 +71,33 @@ the build is signed, and a HOST or SANDBOX marker.  ## Launch on boot -AD starts on login by default. The setting is a checkbox in Settings (checked-by default), and AD keeps the actual Startup entry in sync with it on every-launch: if the checkbox is on and the Startup shortcut is missing, AD-recreates it; if the checkbox is off, AD removes it.+Adom Bridge starts on login by default. The setting is a checkbox in Settings (checked+by default), and Adom Bridge keeps the actual Startup entry in sync with it on every+launch: if the checkbox is on and the Startup shortcut is missing, Adom Bridge+recreates it; if the checkbox is off, Adom Bridge removes it.  To turn it off, untick the launch-on-boot checkbox in Settings. If you have-disabled Adom Desktop under Task Manager's Startup apps instead, AD respects+disabled Adom Bridge under Task Manager's Startup apps instead, Adom Bridge respects that choice and does not re-enable itself. -## How to actually exit AD+## How to actually exit Adom Bridge -Closing the window never exits. The supported way to stop AD is the shutdown+Closing the window never exits. The supported way to stop Adom Bridge is the shutdown command, for example from the CLI: -    adom-desktop desktop_shutdown+    adom-bridge-cli desktop_shutdown  or over the local API:      curl -s -X POST 127.0.0.1:47200/command -d '{"command":"shutdown"}' -With launch on boot enabled, AD will come back at the next login; untick the+With launch on boot enabled, Adom Bridge will come back at the next login; untick the Settings checkbox first if you want it to stay off. -One more lifecycle note: if Hydrogen Desktop dies while AD is embedded, AD+One more lifecycle note: if Hydrogen dies while Adom Bridge is embedded, Adom Bridge does not die with it. It reverts to standalone mode (tray icon back, connections preserved) so the machine stays reachable.  ## Updates never steal your focus -When Adom Desktop restarts itself to apply an automatic update, it comes back in the tray without showing or focusing the window. A window that appears in front of you always has a reason, and the Activity Log records it (look for foreground entries naming who asked and why).+When Adom Bridge restarts itself to apply an automatic update, it comes back in the tray without showing or focusing the window. A window that appears in front of you always has a reason, and the Activity Log records it (look for foreground entries naming who asked and why).

@@ -1,82 +1,82 @@-# Managed runtimes: the Node and Python that Adom Desktop provides
-
-Adom Desktop's bridges (the puppeteer browser bridge, the KiCad and Fusion 360
-bridges, and any third-party bridge you install) are small Node.js or Python
-programs. Instead of asking you to install Node or Python yourself, AD
-provisions both runtimes on its own and shares them across every bridge.
-
-![The Runtimes panel in the Bridges sidebar](runtimes.png)
-
-## Why AD ships its own runtimes
-
-- **Zero pollution of your machine.** If you already have Node or Python on
-  your PATH, AD simply uses it and downloads nothing. If you do not, AD
-  fetches a self-contained portable copy into its own folder. Nothing is
-  registered system-wide, nothing lands in Program Files, and your own
-  development setup is never touched.
-- **No admin prompts, ever.** The portable runtimes are a plain zip extract
-  (Node) and tar.gz extract (Python). There is no MSI, no installer, and no
-  elevation, so you will never see a UAC dialog because of a runtime.
-- **No firewall prompts by default.** AD tells every bridge to bind
-  `127.0.0.1` only (via the `ADOM_BIND_HOST` environment variable), so
-  bridge servers listen on loopback and Windows Firewall stays quiet.
-
-## Where they live
-
-Portable copies are stored under:
-
-```
-~/.adom/adom-runtimes/
-```
-
-with one versioned folder per runtime. Current pinned versions are
-Node 22.11.0 (from nodejs.org) and Python 3.12.13 (a full standalone CPython
-build with venv and pip included).
-
-## How to see their status
-
-Two views of the same information:
-
-- **The Runtimes panel** in the Bridges sidebar of the AD window. Each
-  runtime shows a state dot, its version, and its source: `system` means AD
-  is reusing an install already on your PATH, `adom-managed` means AD
-  downloaded the portable copy.
-- **The CLI verb**, from any connected machine:
-
-```bash
-adom-desktop runtimes
-```
-
-It reports each runtime's state (`absent`, `installing`, `ready`, or
-`failed`), source, and version, plus download progress while an install is
-in flight.
-
-## What gets downloaded, and when
-
-- On every launch, about 3 seconds after boot, AD prewarms both runtimes in
-  the background (the `prewarm_runtimes` setting, on by default). If a
-  system or previously cached runtime exists, this resolves instantly with
-  no download. Only a machine with no usable runtime downloads the portable
-  copy, once.
-- If a bridge needs a runtime before the prewarm finishes, the bridge
-  command returns a "warming" status instead of hanging; it succeeds on
-  retry once the runtime is ready.
-- Turning `prewarm_runtimes` off skips the background download; the runtime
-  is then fetched lazily the first time a bridge actually needs it.
-
-One detail worth knowing: the Windows Store ships a fake `python.exe` stub
-that only offers to install Python. AD detects and rejects that stub, so a
-machine with only the stub gets the real portable Python instead of a broken
-one.
-
-## The guarantees
-
-1. A runtime install never triggers a UAC elevation prompt.
-2. Bridge processes bind loopback (`127.0.0.1`) by default, so no Windows
-   Firewall dialogs.
-3. Your own Node and Python installs are used when present and never
-   modified.
-
-For the developer-facing design and internals, see
-`skills/MANAGED_RUNTIMES.md`; for the full launch-time background task
-timeline, see `skills/PREWARM.md`.
+# Managed runtimes: the Node and Python that Adom Bridge provides++Adom Bridge's bridges (the puppeteer browser bridge, the KiCad and Fusion 360+bridges, and any third-party bridge you install) are small Node.js or Python+programs. Instead of asking you to install Node or Python yourself, Adom Bridge+provisions both runtimes on its own and shares them across every bridge.++![The Runtimes panel in the Bridges sidebar](runtimes.png)++## Why Adom Bridge ships its own runtimes++- **Zero pollution of your machine.** If you already have Node or Python on+  your PATH, Adom Bridge simply uses it and downloads nothing. If you do not, Adom Bridge+  fetches a self-contained portable copy into its own folder. Nothing is+  registered system-wide, nothing lands in Program Files, and your own+  development setup is never touched.+- **No admin prompts, ever.** The portable runtimes are a plain zip extract+  (Node) and tar.gz extract (Python). There is no MSI, no installer, and no+  elevation, so you will never see a UAC dialog because of a runtime.+- **No firewall prompts by default.** Adom Bridge tells every bridge to bind+  `127.0.0.1` only (via the `ADOM_BIND_HOST` environment variable), so+  bridge servers listen on loopback and Windows Firewall stays quiet.++## Where they live++Portable copies are stored under:++```+~/.adom/adom-runtimes/+```++with one versioned folder per runtime. Current pinned versions are+Node 22.11.0 (from nodejs.org) and Python 3.12.13 (a full standalone CPython+build with venv and pip included).++## How to see their status++Two views of the same information:++- **The Runtimes panel** in the Bridges sidebar of the Adom Bridge window. Each+  runtime shows a state dot, its version, and its source: `system` means Adom Bridge+  is reusing an install already on your PATH, `adom-managed` means Adom Bridge+  downloaded the portable copy.+- **The CLI verb**, from any connected machine:++```bash+adom-bridge runtimes+```++It reports each runtime's state (`absent`, `installing`, `ready`, or+`failed`), source, and version, plus download progress while an install is+in flight.++## What gets downloaded, and when++- On every launch, about 3 seconds after boot, Adom Bridge prewarms both runtimes in+  the background (the `prewarm_runtimes` setting, on by default). If a+  system or previously cached runtime exists, this resolves instantly with+  no download. Only a machine with no usable runtime downloads the portable+  copy, once.+- If a bridge needs a runtime before the prewarm finishes, the bridge+  command returns a "warming" status instead of hanging; it succeeds on+  retry once the runtime is ready.+- Turning `prewarm_runtimes` off skips the background download; the runtime+  is then fetched lazily the first time a bridge actually needs it.++One detail worth knowing: the Windows Store ships a fake `python.exe` stub+that only offers to install Python. Adom Bridge detects and rejects that stub, so a+machine with only the stub gets the real portable Python instead of a broken+one.++## The guarantees++1. A runtime install never triggers a UAC elevation prompt.+2. Bridge processes bind loopback (`127.0.0.1`) by default, so no Windows+   Firewall dialogs.+3. Your own Node and Python installs are used when present and never+   modified.++For the developer-facing design and internals, see+`skills/MANAGED_RUNTIMES.md`; for the full launch-time background task+timeline, see `skills/PREWARM.md`.

@@ -1,6 +1,6 @@ # Connection topology -Adom Desktop (AD) connections are not one-to-one. One desktop can talk to many cloud+Adom Bridge (Adom Bridge) connections are not one-to-one. One desktop can talk to many cloud containers, many desktops can share a single container, and both can be true at the same time. This page explains the pieces and the three shapes they form. @@ -10,22 +10,22 @@ same time. This page explains the pieces and the three shapes they form.  There are three moving parts: -- **Adom Desktop (AD)**: the app running on a Windows machine (your laptop, an Azure+- **Adom Bridge (Adom Bridge)**: the app running on a Windows machine (your laptop, an Azure   VM, a conference-room PC). It connects *outward* to relays. - **Relay**: a WebSocket server running *inside each cloud container*-  (`adom-desktop serve`). From outside the container it is reached through the+  (`adom-bridge-cli serve`). From outside the container it is reached through the   container's cloud proxy path, `/proxy/8765/`.-- **CLI**: the `adom-desktop` command-line tool inside the container. It talks to its-  own local relay, which forwards each command to a connected AD and returns the-  AD's JSON response.+- **CLI**: the `adom-bridge` command-line tool inside the container. It talks to its+  own local relay, which forwards each command to a connected Adom Bridge and returns the+  Adom Bridge's JSON response. -So the path for a cloud command is: CLI (in container) -> local relay -> AD (on the+So the path for a cloud command is: CLI (in container) -> local relay -> Adom Bridge (on the Windows machine) -> back the same way.  ## One desktop, many containers -A single AD can connect out to several relays at once. Each relay is a **server-entry** in AD's Connections panel, and each entry has its own live status+A single Adom Bridge can connect out to several relays at once. Each relay is a **server+entry** in Adom Bridge's Connections panel, and each entry has its own live status (`connected`, `reconnecting`, or `disconnected`). Entries persist in `~/.adom/config.json`, and a supervisor inside the GUI re-checks every 30 seconds and auto-reconnects any entry with `autoConnect: true`.@@ -33,57 +33,57 @@ and auto-reconnects any entry with `autoConnect: true`. Servers can be added from the GUI, or programmatically:  ```bash-adom-desktop server_add '{"name":"hydrogen-workspace","url":"ws://localhost:8765","autoConnect":true}'-adom-desktop server_list      # every entry with its live status-adom-desktop server_remove '{"name":"hydrogen-workspace"}'+adom-bridge-cli server_add '{"name":"hydrogen-workspace","url":"ws://localhost:8765","autoConnect":true}'+adom-bridge-cli server_list      # every entry with its live status+adom-bridge-cli server_remove '{"name":"hydrogen-workspace"}' ```  ## Many desktops, one container  One relay can hold **several** ADs at the same time: a laptop, a VM, a-conference-room box. Each AD identifies itself with a **clientName**, resolved in+conference-room box. Each Adom Bridge identifies itself with a **clientName**, resolved in this order: the `--client-name <name>` launch flag, then the Settings field (`config.json` key `client_name`), then the OS hostname.  From the container, discover who is connected:  ```bash-adom-desktop targets+adom-bridge-cli targets # -> {count, targets:[{name, hostname, version, os, connectedAt}]} ```  Then address one machine, or all of them:  ```bash-adom-desktop --target AdomLapper desktop_screenshot_screen   # one named machine-adom-desktop --target all bridge_list                        # every AD at once+adom-bridge-cli --target AdomLapper desktop_screenshot_screen   # one named machine+adom-bridge-cli --target all bridge_list                        # every Adom Bridge at once ```  `--target` is a global flag (it goes before the verb), matches case-insensitively against `clientName` and then `hostname`, and can be defaulted with the `ADOM_TARGET` environment variable (the flag wins). A `--target all` call returns `{broadcast:true, targets:[...], results:{<name>: <verb result>}, summary:{total, ok, failed}}`,-and a timeout or failure on one AD is isolated to that AD's entry in `results`.+and a timeout or failure on one Adom Bridge is isolated to that Adom Bridge's entry in `results`. -**No-target behavior**: with exactly one AD connected, no `--target` is needed.+**No-target behavior**: with exactly one Adom Bridge connected, no `--target` is needed. With multiple ADs connected and no target, the call fails with `{error:"ambiguous_target", connected:[...], _hint}` (exit code 1) rather than guessing which box you meant. A name that matches nothing fails with `{error:"target_not_found", requested, connected:[...]}`. -An AD that reconnects under the same name evicts only its own stale connection;+An Adom Bridge that reconnects under the same name evicts only its own stale connection; differently named machines always coexist on the relay.  ## Many to many -The two shapes compose. Because any AD can hold multiple server entries, and any+The two shapes compose. Because any Adom Bridge can hold multiple server entries, and any relay can hold multiple ADs, the overall topology is many-to-many: your laptop can sit on container A's relay and container B's relay, while container A's relay also holds your VM. -## Peers: what one AD can do about the others+## Peers: what one Adom Bridge can do about the others -From one AD's GUI, the Connections panel shows the *other* ADs on the same relay as+From one Adom Bridge's GUI, the Connections panel shows the *other* ADs on the same relay as an expandable peer list under each server entry. Per peer you can:  - **Info**: view the peer's details.@@ -91,7 +91,7 @@ an expandable peer list under each server entry. Per peer you can: - **Boot**: kick the peer off the relay. This is a transient kick, not a ban: a   healthy peer's supervisor reconnects it within about 30 seconds. - **Block / Unblock**: a per-peer denylist. A blocked peer's GUI-sourced commands-  (screenshot, boot, info) are rejected by your AD, so a shared machine on the same+  (screenshot, boot, info) are rejected by your Adom Bridge, so a shared machine on the same   relay cannot drive yours. Your own cloud containers and local CLI are never   affected by the denylist. @@ -103,16 +103,16 @@ container A's relay. The laptop is *also* connected to container B's relay. From **container A** (two ADs on its relay, so a target is required):  ```bash-adom-desktop targets                          # shows AdomLapper and AzureVM-adom-desktop desktop_list_windows             # FAILS: ambiguous_target, lists both-adom-desktop --target AzureVM desktop_list_windows   # routed to the VM only-adom-desktop --target all hd_status           # both boxes, results keyed by name+adom-bridge-cli targets                          # shows AdomLapper and AzureVM+adom-bridge-cli desktop_list_windows             # FAILS: ambiguous_target, lists both+adom-bridge-cli --target AzureVM desktop_list_windows   # routed to the VM only+adom-bridge-cli --target all hd_status           # both boxes, results keyed by name ```  From **container B** (only the laptop on its relay, so no target needed):  ```bash-adom-desktop desktop_screenshot_screen        # goes to AdomLapper+adom-bridge-cli desktop_screenshot_screen        # goes to AdomLapper ```  Meanwhile the laptop's Connections panel shows two server entries (container A and