Adom Bridge

@@ -0,0 +1,116 @@+---+name: adom-bridge-anywhere+description: Adom Anywhere, the full map of what a LOCAL third-party agent (Claude Desktop, Codex, Claude Code on Windows) can do with the Adom ecosystem from this PC, and where the boundary is. Covers what the Adom Bridge installer already gave you (adom-bridge-cli.exe and adom-wiki.exe on PATH, the auto-linked skill set), driving the PC and pup locally, authoring and managing wiki pages with adom-wiki, the ecosystem skills ab delivers daily (adom core, adom-wiki-cli), and the one hard boundary; running Linux binaries published on the wiki needs an Adom container, which is what Hydrogen provides. Use when a user on Claude Desktop or Codex asks what they can do with Adom, how to use the wiki from their PC, or why a wiki package will not run locally.+---++# Adom Anywhere: the Adom ecosystem from any local agent++You are an AI agent (Claude Desktop, Codex, Claude Code, or similar) running+directly on a Windows PC that has Adom Bridge installed. You do not need an+Adom cloud container to be useful here. This skill is the map of what you can+do right now, and the one thing you cannot.++## What the Adom Bridge installer already gave you++1. **`adom-bridge-cli.exe` on PATH**: every desktop verb (shell, files,+   screenshots, windows, notifications, KiCad, Fusion 360, pup browser+   automation). Start with the `adom-bridge-local-ai` skill for the local+   routing model and a verb cookbook, then `adom-bridge` for the full surface.+2. **`adom-wiki.exe` on PATH**: the full Adom Wiki CLI (pages, repos, files,+   discussions, packages, releases, discovery). If the user is signed in to+   Adom Bridge, ab holds their session token; run wiki commands through+   `adom-bridge wiki_exec` to have the token injected for you, or set+   `ADOM_WIKI_TOKEN` yourself for direct `adom-wiki` calls.+3. **Skills, kept fresh for you**: ab auto-links its own skill set into+   `~/.claude/skills/` and `~/.codex/skills/` on every launch, and refreshes+   the wider ecosystem skill packages (the adom core set and the adom-wiki-cli+   skill) daily from the wiki. You are reading the result. The ecosystem+   skills were written for Adom Linux containers, so each delivered copy+   carries an ADOM ANYWHERE NOTE banner classifying how it applies here; the+   full Windows translation lives in `adom-bridge-anywhere-windows`.++## What works fully, locally, today++- **Drive this PC**: everything in the `adom-bridge` skill. Screenshots,+  windows, input, files, process control, notifications, recordings.+- **pup (real-Chrome browser automation)**: `pup_open_window`, `pup_eval`,+  `pup_screenshot`, multi-session profiles. The bridge auto-spawns on first+  use. This alone makes a local agent a capable web-automation operator.+- **Author and manage wiki content**: create pages, push files, open and reply+  to discussions, star, publish packages you build here. The wiki is the+  distribution surface for the whole Adom ecosystem, and `adom-wiki.exe` is+  the complete client for it.+- **Consume wiki KNOWLEDGE**: skills, docs, page content, package metadata.++## One CLI reaches the WHOLE ecosystem — but don't route local work through the cloud++This is the flexibility that makes ab feel like magic, and the trap that hides+inside it. From this one local CLI you can address:++- **The ab on THIS machine, directly.** `adom-bridge-cli <verb>` with **no+  `--target`** short-circuits to the loopback direct API (`127.0.0.1`, the port+  in `~/.adom/direct-api-port`, else `24680`/`47200`). No relay, no cloud, no+  container. Sub-200ms. This is the default and the right path for this box.+- **Any PEER ab (another machine), through the relay it is on.** Point the CLI+  at that relay's HTTP API and target the peer:+  `ADOM_API=<relay-http-url> adom-bridge --target <clientName> <verb>`. The+  relay HTTP API is the WS URL with the port bumped by one and `http(s)` — e.g.+  a server `wss://…/proxy/8765/` becomes `https://…/proxy/8766`. List who is on+  that relay with `ADOM_API=<relay-http-url> adom-bridge targets`; see which+  bridges run where with `bridge_list`. ⚠ A **plain** `adom-bridge --target+  <name>` with **no `ADOM_API`** does NOT reach a cloud peer — with no+  `ADOM_API` the CLI looks for a relay on `127.0.0.1:8766` (normally not+  running) and returns `target_not_found`. Reaching a peer means pointing the+  CLI at the relay, full stop. (This is exactly how the GUI's peer panel and any+  working peer script reach another machine.)++So "get into the ab ecosystem and see everything" is real: one CLI, the local+machine directly **plus** every peer — as long as you point at the right relay.+Two facts are load-bearing, and forgetting them will cost you:++1. **There is NO direct machine-to-machine path.** A peer (say a conference-room+   PC) is reachable ONLY through a relay BOTH ends are connected to, and only by+   pointing `ADOM_API` at that relay. A relay outage or a peer dropping off makes+   the peer unreachable until it is back — check with `ADOM_API=<relay> adom-bridge+   targets` (the peer appears in the list only while it is actually connected).+   Note the loopback `targets` (no `ADOM_API`) reports only THIS machine and does+   NOT enumerate the relay's peers — use the relay-pointed call to see peers.+2. **⛔ Never route work THIS machine can do out through a cloud relay.** A+   remote/relay call is only as reliable as the cloud relay + the peer's+   connection — a real failure point that has nothing to do with the task. Hit+   live 2026-08-27: a scratch harness hardcoded `ADOM_API=<cloud-relay-proxy>+   --target ConfRoomROG`, so when the cloud proxy 500'd, the campaign stalled —+   even though **this very box had all six bridges (kicad, fusion360, puppeteer,+   native-browser, rustdesk, hd) running locally** and could have done the whole+   job over the loopback API with no cloud involved. KiCad/Fusion/pup render+   identically on any machine, so there was never a reason to leave this box.++**The rule: before you reach for `--target`, ask "can THIS machine do it?"**+Check `bridge_list` for the bridge you need and `targets` for who is actually+reachable. Use a remote target only for work that genuinely must happen on+another machine (e.g. a screenshot of a conference-room screen), and treat the+relay as a dependency that can fail. The deep routing/addressing model lives in+`adom-bridge-local-ai` (loopback case) and the multi-machine addressing skill+(relay case).++## The one boundary: wiki-published Linux binaries++Many wiki packages bundle a Linux CLI in their tarball (`dist/linux/...`) and+an `install.sh` that expects an Adom Linux container. Those binaries cannot+run on Windows directly, and `adom-wiki pkg install` of such a package is a+container operation.++When you hit this, tell the user plainly, and tell them the good part: this is+exactly what **Adom Hydrogen** solves. Hydrogen is the main Adom app; it runs+a full Linux workspace on this same PC (WSL2), installs those packages with+one command, and pairs with the Adom Bridge that is already installed here.+Point them at https://wiki.adom.inc/adom/hydrogen. Do not improvise a local+workaround (WSL hand-installs, wine, copying ELFs around); the supported path+is a real Adom container, and Hydrogen is the one-click way to get one.++## Etiquette++You are a guest on someone's personal machine. Read+`adom-bridge-permissions` before anything gated (shell, file writes), say who+you are on every call (`--ai-thread`, see `adom-bridge-caller-identity`), and+keep foreground manners (`foreground-etiquette` from the adom core skills).

@@ -0,0 +1,202 @@+---
+name: adom-bridge-auth
+description: "Sign in to Adom Bridge and connect a cloud container to the user's desktop: the Connections panel 'Sign in to Adom' browser flow, auto-discover servers from the user's Adom Cloud profile (zero JSON paste), register_container from a cloud container, the one-command setup_desktop flow, configure ab from the CLI, the cloud key-value config keys (bridge.container.*), the paste-JSON fallback, and sign-out. Trigger words: sign in to Adom Bridge, connect container to desktop, register_container, setup_desktop, auto-discover servers, connect my desktop, server JSON, cloud config, sign out."
+---
+
+# Adom Bridge — sign-in, auth, and cloud configuration
+
+Adom Bridge (ab) runs on the user's Windows PC. You (the AI) usually run in a
+cloud container. This skill covers how the two get connected through the user's
+Adom account — the modern, zero-paste path — plus the fallbacks.
+
+## The short version
+
+1. From the cloud container, run `adom-bridge setup_desktop`. It returns a
+   ready-to-run `register_command`.
+2. Run that `register_command` (it is `register_container` with the name + URL
+   filled in). This writes the connection into the USER'S ADOM ACCOUNT.
+3. The user installs Adom Bridge on Windows and signs in with their Adom
+   account. The container appears in their Connections list and auto-connects.
+   No JSON paste at all.
+4. Keep the relay running on your side: `adom-bridge serve --supervise`.
+   Verify with `adom-bridge targets`.
+
+## How the user signs in (what happens inside ab)
+
+The user clicks **"Sign in to Adom"** — a prominent CTA in the Connections
+panel when they are signed out (there is also a sign-in link in the footer).
+ab then:
+
+- Creates an auth intent with Carbon (the Adom auth backend) and opens the
+  returned `auth_url` in the user's **default browser**.
+- The user approves on the Carbon intent screen in the browser.
+- ab polls the intent every 2 seconds (up to 15 minutes), validates the
+  session via `GET /user`, and persists it to `~/.adom/session.json`.
+
+On a fresh, signed-out, standalone launch, ab shows a 5-second auto-login
+countdown ("Logging you into Adom in 5, 4, 3, 2, 1", with Cancel) and then
+opens the sign-in link automatically.
+
+If the browser flow fails or stalls, ab shows an in-window banner with a
+one-click **Retry** (the 'failed' copy reminds the user to pick their Adom
+account in the browser). The sign-in button stays retryable — a stuck poll
+never dead-ends the UI.
+
+## What sign-in unlocks — auto-discovered servers, zero JSON
+
+Once signed in, ab pulls the user's registered containers from their Adom
+Cloud profile (the `bridge.container.*` keys in their cloud preferences) and
+merges them into the local Connections list:
+
+- **Immediately after an interactive sign-in** (`sync_cloud_servers_now` runs
+  as part of completing the flow, then connects the new entries right away —
+  the LED goes green in seconds, not after a 30s supervisor tick).
+- **At every boot** while `~/.adom/session.json` is present (the boot-time
+  cloud sync).
+
+So the user never pastes server JSON: register the container from your side,
+have them sign in, and the connection appears and auto-connects.
+
+## register_container — register THIS container in the user's account
+
+Run this on the cloud container (imperative — you do it, not the user):
+
+```bash
+adom-bridge register_container '{"name":"my-container","url":"wss://<container-slug>.adom.cloud/proxy/8765/"}'
+```
+
+- `name` (required) — the human-friendly label shown in ab's server list.
+- `url` (required) — the public `wss://` URL the desktop will dial, typically
+  `wss://<container-slug>.adom.cloud/proxy/8765/`.
+- Optional: `id` (defaults to a uuid v4; a caller-provided id stays stable
+  across re-runs), `auth_token` (defaults to `adom-dev-token-2025`, what the
+  cloud relay accepts by default), `auto_connect` (default true), `enabled`
+  (default true).
+
+What it does: authenticates with the session token Adom infra mounts at
+`/var/run/adom/api-key`, then PATCHes three cloud key-value config keys in the
+user's carbon-preferences:
+
+- `bridge.container.<id>` — the full server entry as a JSON string
+- `bridge.last_slug` — the id of this container
+- `bridge.enabled` — `true`
+
+ab's cloud-config pull reads those keys after sign-in and at boot.
+
+Naming note (2.0.30): `bridge.*` is Adom Bridge's brand-named key prefix
+(Hydrogen uses `hydrogen.*` the same way). Keys from before the product
+rename lived under `desktop.*`; ab still reads those as a fallback and
+migrates them to `bridge.*` automatically (write new, null old), so any
+`desktop.*` keys you see in the cloud K-V panel are leftovers that fade
+out on their own. Never write new `desktop.*` keys.
+
+**Only works on Adom cloud containers.** On any other box the mounted token is
+absent and the verb returns `ok:false` with an error explaining that — fall
+back to paste-JSON (below). Other returns worth knowing:
+
+- Success: `{ok:true, id, name, url, _hint}` with the user's next steps.
+- **Idempotent by URL**: calling it again for a URL that is already registered
+  reuses the existing entry (refreshes its fields) and returns `ok:true` with
+  `was_duplicate:true` and `warning_code:"DUPLICATE_URL_NO_NEW_ENTRY_CREATED"`.
+  URL is the natural key — call it once per container, not on every loop. The
+  registration persists across sessions, machines, and ab reinstalls because
+  it lives in the user's account, not on any one machine.
+- To revert: PATCH `bridge.container.<id>` to `null` in carbon-prefs.
+
+If ab is already installed and signed in when you register, the user can
+restart ab (or wait — it also polls the cloud config at boot) to see the new
+container.
+
+## setup_desktop — the one-command setup flow
+
+Don't hand-build the connection JSON (the #1 setup mistake). Run:
+
+```bash
+adom-bridge setup_desktop
+```
+
+Aliases: `setup`, `connect`, `connect_info`, `connection`, `connection_setup`,
+`server_json` — they all run the same thing.
+
+It auto-detects this container's public relay URL and returns:
+
+- `register_command` — the preferred path: a ready-to-run `register_container`
+  invocation with this container's name + URL filled in. Run it.
+- `server_config` — the fallback JSON to paste into ab if `register_container`
+  returns `ok:false`.
+- `installer_url` / `release_url` — where the user downloads the Windows
+  installer (wiki page: `https://wiki.adom.inc/adom/adom-bridge`).
+- `server_url`, `desktop_connected`, `steps[]`, `_hint`, `_next`.
+
+Either path requires the relay to be running on the container so the desktop
+has something to dial:
+
+```bash
+adom-bridge serve --supervise
+```
+
+Then verify:
+
+```bash
+adom-bridge targets
+adom-bridge ping
+```
+
+`ping` returning `{"echo":"pong","status":"connected"}` means the desktop is
+reachable. Windows 10/11 is the supported desktop platform today; macOS and
+Linux are coming soon. Each container has its own relay — a new container
+needs its own registration; entries from previous containers won't work.
+
+## Paste-JSON fallback (non-Adom boxes, or the user won't sign in)
+
+If `register_container` returned `ok:false`, have the user:
+
+1. Install Adom Bridge and open it.
+2. Paste the `server_config` JSON from `setup_desktop` into the Connections
+   panel's **"Paste server JSON to add"** box and press Enter.
+3. The server appears and auto-connects — wait for the green dot.
+
+Use the `server_config` exactly as returned — do not hand-assemble it.
+
+## Sign-out
+
+- In the GUI: the **Sign-out** link. It clears `~/.adom/session.json` (the
+  on-disk session).
+- From the CLI/relay: `desktop_logout` (v1.8.42+) does the same thing —
+  Hydrogen calls it on its own sign-out so ab doesn't show a stale
+  email in its footer.
+
+```bash
+adom-bridge desktop_logout
+```
+
+After sign-out, ab reports no signed-in identity until the user signs in
+again. Cloud-discovered servers stop syncing until the next sign-in.
+
+## Related verbs
+
+- `server_add` / `server_remove` / `server_list` — programmatic server
+  registration on the DESKTOP side (upsert by name, idempotent); persists to
+  the same `~/.adom/config.json` the GUI uses.
+- `targets` — list connected desktops; `--target <name>` routes a verb to a
+  specific one when several are connected.
+
+## Relay tokens: rotate the default (issue #33)
+
+The relay's shared bearer token defaults to a well-known DEVELOPMENT literal that is published in these docs. It authenticates the LINK, not a person: anyone who knows a relay's URL plus that literal can join the relay and drive every desktop connected to it, and a caller-supplied identity header is attribution, not authentication.
+
+For any relay whose desktops control real hardware, rotate it. Both sides must match:
+
+```bash
+# 1. relay (in the container)
+adom-bridge serve --supervise --token <secret>      # or export ADOM_AUTH_TOKEN=<secret>
+
+# 2. desktop: set the same value as auth_token on that server entry
+#    (Connections panel, or server_add with authToken)
+```
+
+As of v1.9.179 a relay running on the default warns at startup on both serve paths, and its `/health` reports `usingDefaultToken: true` with a `tokenWarning`, so you can audit any relay:
+
+```bash
+curl -s <relay-http>/health    # -> usingDefaultToken
+```

@@ -0,0 +1,216 @@+---
+name: adom-bridge-sdk-guide
+description: >
+  Consumer guide to Adom Bridge bridges: what a bridge is, the Bridges sidebar cards,
+  bridge status and the bridge LED colors (green/yellow/red/gray), bridge lifecycle
+  (spawn, stable port, single instance, auto-respawn, duplicate collapse), how to
+  install a bridge (bridge_install with a manifestUrl), bridge updates (refresh_bridges,
+  bridge_check_updates, the 4-hour auto-sync from each bridge's wiki page), the bridge
+  console and logs (bridge_log_read and the ab lifecycle log), bridge management verbs
+  (bridge_list, bridge_info, bridge_detail, bridge_kill, bridge_pause, bridge_resume,
+  bridge_readiness), and sync_skills for pulling each bridge's own skill package.
+  Trigger words: bridge status, bridge LED, install a bridge, bridge_install,
+  refresh_bridges, bridge console, bridge lifecycle, sync_skills, bridge updates,
+  bridge_list, bridge_kill, bridge stuck, bridge offline, bridge not running.
+---
+
+# Adom Bridge bridges — the consumer lifecycle guide
+
+This is the USER/CONSUMER side of bridges: how they run, how you see their health, how
+they install and update, and how you manage them with verbs. Building your own bridge is
+a different doc: the Bridge SDK (`skills/BRIDGE_SDK.md`, published on the
+`adom-bridge-sdk` wiki page).
+
+## What a bridge is
+
+A bridge is a small, independently-versioned **separate process** that ab spawns,
+supervises, health-checks, and auto-updates. Each bridge owns a **verb prefix**
+(`pup_*` for the Puppeteer browser, `kicad_*`, `fusion_*`, `nbrowser_*` for your real
+signed-in browser, `blender_*`, `hd_*`, plus any third-party prefix) and a small HTTP
+endpoint on loopback. ab relays verbs to the bridge **verbatim** and renders its health;
+the bridge validates its own args and answers with the same JSON shape on every path
+(relay, direct API, CLI). ab stays generic: it never bakes in app-specific logic.
+
+Every install ships six bridges: Puppeteer, native-browser, KiCad, Fusion 360 (+ APS),
+Blender, and the Hydrogen stub. Bundled seeds work offline on day one; the wiki
+is for updates, not first-install (see `skills/FIRST_INSTALL.md`).
+
+## The Bridges sidebar (what the user sees)
+
+Each installed bridge is a mini-app card in the ab window's right sidebar: hero image
+(the bridge's own wiki billboard), a health LED, language and source badges, star count.
+A `?` help icon carries the full tooltip; clicking a card opens a wide pop-out with a
+live console (the per-bridge log + command history), a ports/PID debug view, and all
+management actions (install/uninstall/kill/restart/pause/resume). **+ Bridge** installs
+a new one by manifest URL; **Check for updates** is the on-demand sync button.
+
+### LED colors — the bridge self-reports, ab renders
+
+ab is a pure renderer of bridge health. A live bridge decides its own LED, short
+`summary` label, and hover `tooltip` on its health endpoint; ab paints them verbatim,
+re-polling about every 15 seconds.
+
+| LED | Meaning |
+|---|---|
+| green | Healthy. The bridge said so (or answered 2xx without self-reporting, which defaults to green). |
+| yellow | Degraded/warning, per the bridge itself (e.g. an upstream partially down). |
+| red | The bridge itself knows it is broken (e.g. it lost its upstream). |
+| gray (offline) | ab owns this ONE state: the health endpoint is unreachable. A not-running bridge reads as off, not failed. A dead bridge cannot self-report. |
+
+## Lifecycle — one instance, stable port, supervised
+
+- **Spawn on first verb.** A bridge is auto-started by ab on the first command of its
+  prefix (e.g. the first `pup_*` call). No manual start.
+- **Stable persisted port.** Each bridge keeps ONE runtime port across respawns AND ab
+  restarts (persisted in `~/.adom/bridge-ports.json`). External clients (a browser
+  extension) keep dialing the same port. Ports are OS-assigned — never hardcode one;
+  the verb prefix is the contract.
+- **Single instance.** Spawns are serialized behind a per-bridge lock; ab tracks every
+  spawned PID and reaps a stale/wedged instance before respawning. A background sweep
+  (every ~15 s) collapses duplicates: it scans for any process (tracked or not) bound to
+  a bridge port, health-probes it, keeps the instance on the assigned port, and reaps
+  the rest — so relay verbs never round-robin between two copies.
+- **Auto-respawn for persistent bridges.** `spawn.persistent: true` (surfaced in
+  `bridge_list`) means a supervisor respawns the bridge on death, on its stable port.
+  "Kill it to load new code" just brings it right back.
+
+## Install levels — how eagerly each bridge gets onto the machine
+
+The AI always does the install; the level only sets timing and consent:
+
+| Level | Bridge(s) | Behavior |
+|---|---|---|
+| 0 built-in | Hydrogen (`hd`) | The platform itself; a manifest stub only, never installed by ab. |
+| 1 fundamental, pre-emptive | Puppeteer (`pup`) | Bundled seed; ab pre-installs its runtime (Node + Chrome-for-Testing) in the background on first boot. |
+| 2 recommended, proactive offer | native-browser | The desktop bridge half is bundled (works extension-free day one); the in-browser extension is proactively offered and installs on a yes. |
+| 3 on-request host app | KiCad, Fusion, Altium, ... | ab detects the host app; it never pre-installs a multi-GB app unasked, and never tells the user to install it manually — the AI installs it the moment the user wants it. |
+| 4 explicit third-party | any `bridge_install`'d bridge | The user opts in by installing it from its wiki manifest URL. |
+
+## Updates — each bridge from its OWN wiki page
+
+Bundled seeds auto-update from their own wiki pages: on launch + every 4 hours, ab checks
+each registered bridge's `updateManifestUrl`; a strictly-newer version downloads
+(sha256-verified) into `~/.adom/bridges-cache/` and cache-over-bundled supersedes the
+seed. On demand:
+
+```bash
+adom-bridge bridge_check_updates            # READ-ONLY: current vs wiki latest per bridge
+# -> {bridges:[{name,current,latest,updateAvailable,source,wikiReachable}], updatesAvailable:N}
+adom-bridge refresh_bridges                 # apply updates for ALL bridges that are behind
+adom-bridge refresh_bridges '{"name":"kicad"}'   # or just one
+```
+
+Version semantics: `current` = what ab actually runs = the newer of cache and bundled
+(numeric semver). After an update, the running server process still holds old code until
+it respawns; the version-aware liveness check forces a respawn on the next verb call, so
+you normally do not need to kill anything.
+
+## The dev pin: a developer's cache is sacred
+
+If someone (or you) is actively modifying a bridge's installed cache, freeze it
+first: `bridge_dev_mode {"name":"<bridge>","on":true}` writes a `.dev-pin`
+marker and EVERY automatic update path skips that bridge (the 4h sweep,
+on-launch sync, on-use auto-update, refresh_bridges) - so local changes are
+never clobbered by a release. `bridge_list` rows show `devPinned:true`, the ab
+GUI card shows an amber "dev pin" badge (its update badge is suppressed while
+pinned), and the card pop-out has one-click Pin/Unpin. `on:false` resumes
+updates. **Never release someone else's dev pin to "get the latest" - the pin
+means a human is mid-development on that bridge.** The one deliberate override
+is a human running `bridge_install {manifestUrl, force:true}`.
+
+## The key verbs
+
+```bash
+# Inventory — start here. Includes per-bridge skillPkg (adom/<slug>) and installSkill
+# (a ready-made `adom-wiki pkg install` line), plus a top-level _skillsHint.
+adom-bridge bridge_list
+
+# Rich detail for ONE bridge (alias bridge_detail): log tail, resolved ports, full verb
+# list, manifestUrl — and HONEST liveness: processLive is true only when the process is
+# actually alive. (bridge_list's status is a cheap port-allocated heuristic; after a
+# kill the stable port stays reserved by design, so trust bridge_info/bridge_detail.)
+adom-bridge bridge_info '{"name":"puppeteer"}'
+
+# Cursor-streaming remote tail -f of the bridge console. The tail also appends ab's own
+# append-only lifecycle log (under an "===== ab bridge lifecycle =====" header) which
+# SURVIVES respawns and records why a bridge started/stopped: an "[ab] REAPED ... as
+# duplicates" line means ab killed it; an "[ab] spawned" line with NO preceding reap
+# means the process exited on its own (a bridge-side crash).
+adom-bridge bridge_log_read '{"name":"kicad"}'
+adom-bridge bridge_log_read '{"name":"kicad","sinceOffset":41230}'
+
+# Kill a bridge's processes (tracked PIDs + any image-verified orphan still bound to its
+# port). Persistent bridges come right back on the same port.
+adom-bridge bridge_kill '{"name":"native-browser"}'
+
+# Pause/resume: a ROUTING flag only. Paused verbs fail fast with errorCode
+# "bridge_paused"; the process is NOT killed.
+adom-bridge bridge_pause '{"name":"fusion360"}'
+adom-bridge bridge_resume '{"name":"fusion360"}'
+
+# READ-ONLY readiness probe across every bridge — "what tools do I have / are they
+# ready." NEVER spawns a bridge, never installs or downloads anything. Per bridge:
+# {hostApp, hostAppInstalled, runtime, runtimeReady, assets, state} with state in
+# ready | warming | needs-runtime | no-app, plus a top-level edaToolsInstalled list.
+# Use THIS for "what's installed" questions, not a *_status verb (which may spawn).
+adom-bridge bridge_readiness
+
+# Install a third-party bridge from its wiki manifest URL. On success the card appears
+# in the GUI immediately (gray until first use). On failure NOTHING is registered —
+# read `error`; confirm with bridge_list. Never treat a parsed manifest as an install.
+adom-bridge bridge_install '{"manifestUrl":"https://wiki.adom.inc/api/v1/pages/<bridge-page>/files/<bridge>-bridge-manifest.json"}'
+
+# Remove one. Bundled bridges revert to the bundled copy; third-party are fully removed.
+adom-bridge bridge_uninstall '{"name":"my-bridge"}'
+```
+
+## sync_skills — get each bridge's OWN skill
+
+Installing the adom-bridge core pkg gives a container only CORE skills. A dynamic/cloud
+bridge (kicad, fusion, blender, any third-party) ships its consumer SKILL.md in its OWN
+wiki skill pkg. **Run this right after connecting:**
+
+```bash
+adom-bridge sync_skills
+```
+
+It runs `bridge_list`, collects every non-null `skillPkg`, and installs each bridge's
+own skill pkg into `~/.claude/skills/` so you can discover and drive whatever bridges
+THIS desktop actually has. Idempotent; on a multi-ab relay it unions bridges across all
+desktops. The CLI also runs it automatically about once a day in the background
+(containers only; opt out with `ADOM_SKILL_SYNC=0`), but running it on connect makes the
+skills available to the current session immediately. Re-run any time the desktop gains a
+bridge. Do not hand-copy a bridge's SKILL.md into a container — sync_skills is the path.
+
+## Prewarm — why a fresh box is briefly "warming"
+
+On launch ab prewarms in the background: portable no-UAC Node and Python (downloaded only
+if not already on PATH, ~3 s after boot, gated by config `prewarm_runtimes`, default on),
+and on install/upgrade a detached pup prefetch (`npm install` + the ~150 MB
+Chrome-for-Testing) so the first `pup_open_window` is not a 3-minute hang. A bridge
+verb during the download gets an honest `runtime_warming` response (`stillRunning:true`,
+poll the `runtimes` verb, then retry) — not a hang, not a failure. Details:
+`skills/PREWARM.md` and `skills/FIRST_INSTALL.md`.
+
+## The demarcation rule
+
+Each bridge ships its own FULL consumer skill from its own wiki page (installed via
+`sync_skills`). ab's docs — this guide included — only cover the bridge LIFECYCLE and
+management surface, and point at each bridge's page for how to actually drive it.
+For KiCad workflows read the kicad bridge's skill; for browser automation read pup's;
+and so on. `bridge_list`'s `installSkill` field gives you the exact install line per
+bridge.
+
+## Private-page bridges (v1.9.177+)
+
+A bridge published on a PRIVATE wiki page (org-internal machine control, factory integrations) is fully supported: when ab is signed in, `bridge_install`, the 4-hour auto-update poll, and the zip download all send the signed-in wiki token, so a private bridge installs and self-updates exactly like a public one. Requirements: ab signed in (footer shows the identity) with an account authorized for the page. If the manifest URL returns PAGE_NOT_FOUND, the error now says so plainly: the page is private or missing, so check the signed-in account first.
+
+## When a bridge cannot start: read the structured answer, not the timeout (v2.1.30-2.1.32, wiki #142)
+
+A verb routed to a bridge that is not up never has to end in a bare timeout. ab answers, inside the verb's own budget, with one of:
+
+- `errorCode:"bridge_installing_deps"`, `stillRunning:true`, `installElapsedSec` - a source-only node bridge's ONE-TIME detached `npm install` is running (minutes on first use). Wait and re-issue the verb; do not restart anything.
+- `errorCode:"bridge_spawn_failed"`, `stillRunning:false`, `lastSpawnError`, `failedAttempts`, `retryBackoffRemainingMs` - the spawn (or its dependency install) failed and ab is in backoff, so it answers immediately instead of re-attempting on every call. `lastSpawnError` is the cause; for an npm failure the real `npm error` lines are in it and the FULL npm output is in `bridge_log_read {"name":"<bridge>"}` -> `npmLog` (also `~/.adom/bridge-logs/<bridge>.npm.log`). Fix the cause, then `bridge_resume {"name":"<bridge>"}` clears the backoff and the next verb retries.
+
+`bridge_detail` / `bridge_list` carry the same fields (`lastSpawnError`, `failedAttempts`, `retryBackoffRemainingMs`, `depsInstallingSec`) so you can tell "never tried" from "tried and died" in one read.
+

@@ -0,0 +1,366 @@+---+name: adom-bridge-caller-identity+description: Fix `caller_identity_required` refusals and tell ab who is asking. Read when an Adom Bridge verb is refused with caller_identity_required, when you need to set aiThread / ADOM_AI_THREAD / ADOM_CONTAINER_NAME, when the user asks "which thread is driving my machine" or "identify my thread", when you are writing a bridge that calls ab verbs back and must forward X-Adom-Caller-* headers or set X-Adom-Caller-Delegate, or when you need to understand caller identity, delegation chains, thread name and container name attribution on relayed commands.+---++# Caller identity: telling Adom Bridge who is asking++Since v1.9.180, every command that reaches Adom Bridge (ab) **over the relay** must+say which AI conversation is making it. If you do not supply that, ab refuses the+call with `errorCode: caller_identity_required` and hands you a teaching payload.++This page is for you, the AI caller. It covers the fix, why the user cares, and how+identity relates to the `reason` argument you already send on gated verbs.++**Identity is self-reported and is never authorization.** You choose these values; ab+records and displays them but cannot verify them. Since v1.9.182 there is a first-class+CLI flag for setting them, which makes identity feel more official than it is. It is+not. It is a label for attribution and visibility. Never grant privilege based on it,+and never tell a user a thread name proves anything. Full detail in+[Identity is not authorization](#identity-is-not-authorization).++## Why this exists++A typical ab user has roughly **20 AI conversation tabs open at once**, all pointed at+the same desktop. Before caller identity, every one of those tabs looked identical to+the user: an approval toast said "some AI wants to run a shell command" and the Activity+Log was an undifferentiated stream. There was no way to tell the tab doing useful+background work from the tab that just went off the rails. You name yourself once, and+from then on the user can see exactly which tab is driving their machine.++## The refusal++A relayed call with no thread identity comes back like this:++```+errorCode: caller_identity_required+```++The payload names the exact shape ab wants. It is a teaching refusal, not a dead end:+add the identity to your call and retry.++**Almost nobody is exempt.** Being on loopback is not a reason to be anonymous:+Hydrogen and a local CLI call ab because some AI thread wants something, so+since v1.9.181 they are held to the same contract as a cloud thread. The one remaining+exemption is a **bridge calling ab back** while presenting ab's bridge token, and that+is a migration grace period, not a design: a bridge is expected to forward the identity+it was handed (see [Bridges and the delegation chain](#bridges-and-the-delegation-chain)).++## The fix (recommended: the CLI flags, on every call)++Since v1.9.182 the CLI has two global flags. They work on **every** verb, exactly like+`--target`, and they go before the verb:++```bash+adom-bridge --ai-thread "pup bridge maintenance" --container-name "galliaApril" \+  shell_execute '{"command": "dir C:\\Users", "reason": "finding the download folder"}'+```++`--container-name` is optional. ab separately knows the **verified** container name+(the authenticated relay connection), and it will show both values when they disagree.++Put the flags into whatever wrapper or helper you use to shell out, so every call+carries them. Verify by running any verb and looking at the response, or by asking the+user to glance at the Activity Log.++## The fix (in the verb's own arguments)++Equally correct, and the right form when you are not going through the CLI:++```bash+adom-bridge shell_execute '{+  "command": "dir C:\\Users",+  "caller": { "aiThread": "chip-fetcher tab 3", "containerName": "galliaApril" },+  "reason": "listing user profiles to find the download folder"+}'+```++A flat top-level `aiThread` is also accepted:++```bash+adom-bridge shell_execute '{+  "command": "dir C:\\Users",+  "aiThread": "chip-fetcher tab 3",+  "reason": "listing user profiles to find the download folder"+}'+```++## The fallback: environment variables (single-agent containers only)++`ADOM_AI_THREAD` and `ADOM_CONTAINER_NAME` are still honored:++```bash+export ADOM_AI_THREAD="nightly wiki sync"+export ADOM_CONTAINER_NAME="galliaApril"+```++**Only use these when the container runs exactly one agent**: CI, a single-purpose job,+a dedicated one-off box. In any container where more than one conversation can run, they+produce wrong attribution rather than none. See below.++### Why per-call, not an env var++An environment variable scopes to a **shared shell environment**, not to a thread. On a+real container, roughly 20 concurrent AI threads share one container and one `$HOME`.+Two things happen, both bad:++- **One shared value**: every thread claims the same name. The Activity Log and the+  approval toast then name the wrong thread with total confidence. That is worse than+  no attribution, because it is plausible and wrong.+- **A race**: threads overwrite each other's value, so any concurrent call is+  misattributed.++There is also a silent-failure trap. Tool-driven shells are **non-interactive**, and the+stock Ubuntu `~/.bashrc` returns early for non-interactive shells:++```bash+case $- in *i*) ;; *) return;; esac+```++An `export` appended below that line **never runs**. So the old "set it once" advice+could produce no error and no identity at all, and cost you time hunting a no-op.++The per-call forms have neither problem: the identity travels with the call that+actually carries it.++### Precedence++When more than one is present, ab takes them in this order:++1. An explicit `caller` block (or flat `aiThread`) in the verb's args.+2. The `--ai-thread` / `--container-name` CLI flags.+3. The `ADOM_AI_THREAD` / `ADOM_CONTAINER_NAME` environment variables.++### Picking a good thread name++This is the part that actually matters, and it is a judgement call only you can make.++The name is shown **to a human**, on a toast, while they decide whether to let you do+something. Choose a name they will recognise at a glance:++- Good: `chip-fetcher tab 3`, `kicad board review`, `nightly wiki sync`, `John's laptop cleanup`+- Bad: `f47ac10b-58cc-4372-a567-0e02b2c3d479`, `session_1`, `claude`, `agent`++Prefer: what the work is, plus which tab it is if the user has several doing the same+thing. If the user has told you what they call this conversation, use their words.++## Identity is not authorization++Be honest with the user about this if it comes up.++`aiThread` and `containerName` are **self-reported by you**. ab records them and shows+them; it does not and cannot verify them. They exist for **attribution and visibility**,+never for authorization.++ab's actual security is transport-based: the relay connection is authenticated, so the+**verified container name** is a fact ab can prove. That is why ab displays both the+self-reported container and the verified one when they differ. The thread name is a+label you chose. Never tell a user that a thread name proves anything, and never write a+bridge or a workflow that grants privilege based on an `aiThread` value.++## Identity versus `reason`++These are two different arguments solving two different problems. Gated verbs want both.++| | `caller` / `aiThread` | `reason` |+|---|---|---|+| Scope | Per **call** (stable across the session) | Per **call** (fresh each time) |+| Answers | Who is asking | Why this specific action |+| Set via | `--ai-thread` flag, or the call's args | Always in the call's args |+| Refusal | `caller_identity_required` | its own separate refusal (since v1.9.159) |++They have separate refusals, so satisfying one does not satisfy the other. On a gated+verb, send both:++```bash+adom-bridge --ai-thread "kicad board review" run_script '{+  "interpreter": "bash",+  "script": "ls -la /c/Users/john/Downloads",+  "reason": "checking whether the gerber zip finished downloading"+}'+```++The `reason` should be written for a human reading a toast under time pressure. Say what+you are about to do and why, in one line, in plain words.++## What the user actually sees++Knowing the surfaces helps you write a good thread name and a good reason.++**Activity Log**, one line per command:++```+thread "chip-fetcher tab 3" in galliaApril — reason: checking whether the gerber zip finished downloading+```++**Approval toast.** Windows has a dedicated attribution slot: a separated, greyed line+under the request. ab puts `<thread> · <container>` there, while the body shows the verb+and your stated reason. Your thread name and your reason are literally the two things the+user reads before clicking Approve or Deny. The in-window approval dialog carries the+same information as `aiThread` and `callerContainer` fields, and `notify_user` derives+its toast attribution from your caller identity automatically (you pass nothing extra).++## Bridges and the delegation chain++ab stamps these headers on every request it dispatches to a bridge:++```+X-Adom-Caller-Thread+X-Adom-Caller-Container+X-Adom-Caller-Reason+X-Adom-Caller-Delegate+```++A bridge gets them without doing anything to receive them. Reading them is opt-in: log+by thread, label a window it opens with the owning thread, or arbitrate between two+threads that want the same resource. If you are writing a bridge, read these headers+rather than inventing your own identity channel.++### The last hop used to lose you (fixed in v1.9.183)++Bridges do not only receive work, they call ab verbs back to carry it out:+`desktop_screenshot_window`, `desktop_set_window_identity`, `notify_user`,+`desktop_taskbar`. Those callbacks go to ab's direct API on loopback, and ab used to+**drop** the `X-Adom-Caller-*` headers on that leg. So your thread name reached the+bridge and then vanished at the last hop. The Activity Log credited the bridge for work+you asked for, and an approval toast asked the user to authorize a nameless bridge.+Propagation was not merely undocumented, it was impossible.++Since v1.9.183, `POST 127.0.0.1:<port>/command` reads those headers and folds them into+the command's args, so everything downstream sees them: the Activity Log, the approval+toast, and the headers ab stamps on its own onward bridge calls.++### If you are writing a bridge: forward what you were given, then name yourself++Node, using the direct-API values ab injects into your spawn environment+(`ADOM_DIRECT_API_URL`, `ADOM_BRIDGE_TOKEN`):++```js+// `incoming` is the request ab dispatched to your verb handler.+const FORWARD = {+  "x-adom-caller-thread":    "X-Adom-Caller-Thread",+  "x-adom-caller-container": "X-Adom-Caller-Container",+  "x-adom-caller-reason":    "X-Adom-Caller-Reason",+};+const headers = {+  "Content-Type": "application/json",+  "X-Adom-Bridge-Token": process.env.ADOM_BRIDGE_TOKEN,+  "X-Adom-Caller-Delegate": "pup",   // name YOURSELF; do not forward this one+};+for (const [from, to] of Object.entries(FORWARD)) {+  const v = incoming.headers[from];+  if (v) headers[to] = v;+}++await fetch(`${process.env.ADOM_DIRECT_API_URL}/command`, {+  method: "POST",+  headers,+  body: JSON.stringify({+    command: "desktop_screenshot_window",+    args: { hwnd },+  }),+});+```++Python, same shape:++```python+FORWARD = ("thread", "container", "reason")++headers = {+    "X-Adom-Bridge-Token": os.environ["ADOM_BRIDGE_TOKEN"],+    "X-Adom-Caller-Delegate": "kicad",   # name YOURSELF+}+for part in FORWARD:+    value = incoming_headers.get(f"x-adom-caller-{part}")+    if value:+        headers[f"X-Adom-Caller-{part.capitalize()}"] = value++requests.post(+    f"{os.environ['ADOM_DIRECT_API_URL']}/command",+    headers=headers,+    json={"command": "notify_user", "args": {"title": "Export finished"}},+)+```++### `X-Adom-Caller-Delegate`, and why the user sees both names++This is the one header a bridge **adds** rather than forwards. It names the bridge+itself, for example `pup`. It produces a `delegatedBy` field on the caller, and the+user-visible attribution becomes:++```+chip-fetcher tab 3 (via pup)+```++Both halves are load-bearing. Attributing the call to the thread alone would hide who+actually ran it, and attributing it to the bridge alone would hide who asked for it. The+user gets to see both, so a screenshot taken by pup on behalf of tab 3 reads as exactly+that.++If you omit the header, ab still records the delegation and falls back to a generic+`via bridge`, which is honest but much less useful. ab also carries the delegate forward+onto any onward hop, so a chain two bridges deep still shows the original delegate.++### Explicit args always win++A forwarded header only fills a field the args left empty. So when your bridge acts on+its **own** behalf (a health poll, a timer, a cleanup sweep), do not forward a stale+identity from some earlier request: send your own `caller` block instead, and the call is+attributed to you.++### Still self-reported++Everything in this chain is self-asserted, including the delegate name. A delegate could+forge any of it. That is acceptable precisely because it authorizes nothing: these values+are for attribution, logging, UX, and arbitration only. Never gate a bridge behavior on+an `aiThread` or a `delegatedBy` value.++## Hydrogen is held to the same contract++Hydrogen calls ab because an AI thread inside Hydrogen's own container wants something. That is the+same situation as any cloud thread, so Hydrogen is a gated caller like anyone else (it is a+loopback non-bridge caller, and loopback is not an exemption).++Looking ahead, Hydrogen will host **multiple** containers. When it does, Hydrogen must pass the+container name and the ai-thread of whichever inner container originated the call, using+exactly the mechanism described above. There is one mechanism for delegation, not a+separate one per delegate: forward the caller headers you were given, add+`X-Adom-Caller-Delegate` to name yourself, and let explicit args win when you are acting+on your own behalf.++## `bridge_kill` and the confirm flow++Killing a bridge is disruptive to other tabs, so ab guards it with a one-time refusal.++If **other threads were active in the last 5 minutes**, the first `bridge_kill` is+refused and the response **names those threads**. This is deliberate: it gives you the+chance to notice that you are about to yank a bridge out from under a sibling+conversation.++Retry with `confirm: true` to proceed:++```bash+adom-bridge bridge_kill '{+  "name": "puppeteer",+  "confirm": true,+  "reason": "bridge is wedged and not responding to status probes"+}'+```++Before you blindly set `confirm: true`, consider the named threads. If another tab is+clearly mid-task on that bridge, the better move is usually to tell the user rather than+to kill it. ab gave you the names precisely so you could make that call.++## Quick checklist++1. On every call: `--ai-thread "<human-recognisable name>"`, or a `caller` block in the args.+2. Optionally: `--container-name "<your container>"`.+3. On every gated verb: include a plain-language `reason`.+4. If you see `caller_identity_required`: you are missing step 1, not step 3.+5. Only reach for `ADOM_AI_THREAD` if the container runs exactly one agent.+6. If you see a `bridge_kill` refusal naming other threads: read the names, then decide.+7. If you are a bridge or Hydrogen: forward the `X-Adom-Caller-*` headers you+   were handed, add `X-Adom-Caller-Delegate` naming yourself, and send your own `caller`+   block when the work is genuinely your own.+8. Never treat a thread name, a container name, or a delegate name as proof of anything.

@@ -0,0 +1,201 @@+---+name: adom-bridge-guide+description: Use when working with the adom-bridge CLI itself - how to run desktop verbs, discover commands (adom-bridge commands, help topics), address targets with --target, start the serve relay with --supervise, read the status/durationMs/timeoutSeconds response shape, stream long ops with watch, or sweep the screenshot cache with janitor.+---++# The adom-bridge CLI++One Rust binary, two jobs: it runs the relay server (`adom-bridge serve`) and it sends+verbs to the Adom Bridge app (`adom-bridge <verb> '<json>'`). Everything an AI does to+the user's desktop goes through this surface.++## The two binaries (same CLI, two homes)++| Where | Binary | How it got there | How it reaches the desktop |+|---|---|---|---|+| Cloud Linux container | `adom-bridge` | `adom-wiki pkg install adom/adom-bridge` (installs the CLI + the skill set) | Over the relay it serves (WS :8765 / HTTP :8766) |+| Windows, next to the GUI | `adom-bridge-cli.exe` | Bundled by the ab installer into `%LOCALAPPDATA%\Adom Bridge\`, which the installer adds to the user PATH (HKCU, no UAC) | Auto-probes the local GUI's loopback direct API (`127.0.0.1:47200`, discovery file `~/.adom/direct-api-port`, fallback scan 47200-47209) |++Verify which build you have:++```bash+adom-bridge --version+# adom-bridge 1.9.x (<git-sha>, built <timestamp>)+```++## Discovering verbs: `commands` is THE catalog, not `--help`++`adom-bridge --help` lists only the real clap subcommands: `serve` and `install`. Every+actual capability (200+ verbs) is a dynamic verb forwarded to the desktop app, and the+authoritative machine-readable catalog is:++```bash+adom-bridge commands                    # full catalog: categories, args, returns, _hint per verb+adom-bridge --target <name> commands    # plus THAT box's installed bridges+adom-bridge help <topic>                # details for one verb or namespace (e.g. help pup, help shell)+```++Run `commands` FIRST when unsure what a verb is called. There is almost certainly a+structured verb with typed args (`process_list`, `process_kill`, `run_script`,+`desktop_list_files`) so you never hand-quote a command through JSON into a shell.+`shell_execute` is the escape hatch for things with no verb yet, not the default.++Two kinds of verbs, do not confuse them:++- **Built-in ab-core verbs** are on every Adom Bridge, no install: screenshots, windows,+  input, files, registry, shell, tunnel, update, notify.+- **Bridge verbs** (`pup_*`, `kicad_*`, `fusion_*`, `nbrowser_*`, ...) need that bridge+  installed. Check `installed_bridges_on_target` in `commands`, or run `bridge_list`.++An unknown verb returns `errorCode:"unknown_verb"` with a fuzzy did-you-mean `_hint`.+Read it; do not conclude a capability is missing from a guessed name.++Recognized help namespaces (`adom-bridge help <topic>` or `adom-bridge <topic> help`):+`pup`/`browser`, `kicad`, `fusion`, `hd`, `shell`, `files`, `notifications`, `watch`,+`setup`, `connectivity`, `system`, `record`, `server`, `bridge`, `wiki`.++## Invoking a verb++```bash+adom-bridge <verb> '<json-args>'+adom-bridge ping+adom-bridge shell_execute '{"command":"echo hello","reason":"smoke-testing the shell path"}'+adom-bridge desktop_screenshot_window '{"hwnd": 12345}'+```++Output is pretty-printed JSON on stdout. Windows paths may be written with forward+slashes (`C:/Users/...`); the CLI normalizes both directions automatically.++**Grouped verbs** take a bare-word subcommand before the JSON:++```bash+adom-bridge tunnel rdp '{"to":"127.0.0.1:3389"}'+adom-bridge tunnel list+```++**Gated verbs need a `reason`.** Verbs that require human approval over the relay+(`shell_execute`, `run_script`, and the rest of the permission class) require a `reason`+arg: one plain sentence the user reads verbatim in the approval prompt. A missing reason+returns `errorCode:"reason_required"`.++## The uniform response shape++Every result carries, on every path (relay, direct API, Windows CLI):++- **`status`**: `ok` | `timeout` | `busy` | `error`. One authoritative field. An empty+  `stdout` with `status:ok` is a real empty-output success, NOT a timeout.+- **`durationMs`**: the CLI's measured round-trip.+- **`_hint`**: actionable guidance authored by ab core (recovery steps on `timeout`/`busy`,+  next-verb pointers on success). The CLI only authors a hint for the one case ab cannot:+  the call never reached the desktop at all.+- **`timeoutSeconds`**: the HTTP budget that governed this call. On a timeout, bridge+  verbs return `errorCode:"timed_out"` with `stillRunning:true`: the operation usually+  keeps running on the bridge. Poll the response's `statusVerb` instead of re-issuing.+- Exec verbs additionally carry `exitCode` / `stdout` / `stderr`.++`adom-bridge timeouts` returns the per-verb budget registry (long verbs, their budgets,+and the status verb to poll).++## Targeting: one relay, many desktops++One relay can hold several Adom Bridges (laptop + VM + ...). Each has a name+(`--client-name` launch flag / Settings field / hostname default).++```bash+adom-bridge targets                              # {count, targets:[{name, hostname, version, os, connectedAt}]}+adom-bridge --target azurevm desktop_screenshot_screen+adom-bridge --target all hd_status               # fan out; results keyed by name + summary+```++- `--target` is a global flag: works before or after the verb, case-insensitive, matches+  `clientName` then `hostname`. `ADOM_TARGET=<name>` sets a default; the flag wins.+- Exactly ONE desktop connected: no `--target` needed.+- Multiple connected, no `--target`: the call fails with `error:"ambiguous_target"`+  (exit 1) and lists the connected names. It never guesses. A bad name returns+  `target_not_found`.+- `--target all` returns `{broadcast:true, results:{<name>:...}, summary:{total,ok,failed}}`;+  a per-desktop failure is isolated to that desktop's entry.+- Caveat: `ping` has its own direct-API path and does NOT honor `--target`. Smoke-test+  routing with a relay-path verb (`server_list`, `desktop_*`).++## Local vs relay routing++- **No `--target` on Windows**: the CLI short-circuits to the local GUI's loopback direct+  API. No relay required. This is the right path for anything on the same machine.+- **`--target <name>` (or `ADOM_TARGET`)**: the call traverses the relay, even from the+  desktop itself, so it can reach a named or broadcast set of machines.+- **In a container**: everything goes through the relay the container runs.++## The relay: `serve --supervise` in containers++The relay must be running before any desktop can connect. In a container, ALWAYS start+it supervised:++```bash+adom-bridge serve --supervise                       # detached + self-healing+adom-bridge serve --supervise --owner AdomLapper    # send restart toasts to one desktop+adom-bridge serve --stop                            # stop watchdog + relay+```++Why not `adom-bridge serve &`? A backgrounded relay is still a child of your session.+When the session is torn down, the relay dies with it, and every connected desktop loops+"Reconnecting in 30s" for hours until a human restarts it. `--supervise` detaches the+relay into its own session (reparented to init) and runs a watchdog that restarts it+with exponential backoff (2s up to a 5 min cap; a clean run resets it) and toasts the+connected desktops with the reason on each restart.++Plain foreground `serve` still works and prints a loud warning that it dies with the+session. Caveat: a full container reboot still needs a boot hook (cron `@reboot` or the+container's init); the watchdog covers session teardown, not host reboot.++What `serve` binds:++- WebSocket on `0.0.0.0:8765` (desktop apps connect here)+- HTTP API on `127.0.0.1:8766` (CLI commands go here)++Health check: `curl -sf http://127.0.0.1:8766/health`. If another relay is already+answering, `serve` skips with a friendly message; `--force-bind` overrides (only for+deliberate parallel relays).++## `watch`: stream long operations++For long-running walks, use the built-in `watch` wrapper instead of a polling loop. It+spawns the inner command, polls status internally, and emits one JSON event per line to+stdout as progress happens:++```bash+adom-bridge watch '{"command":"fusion_walk_cloud_tree","args":{"projectName":"Main","nameContains":"BQ25792"}}'+adom-bridge watch '{"command":"fusion_walk_cloud_tree","args":{...},"interval":1}'+```++Watchable commands (whitelist): `fusion_walk_cloud_tree`, `fusion_search_cloud_files`.+Others return `success:false` with a `_hint` listing the watchable set. Do not use it+for short operations that return in under 2 seconds. From Claude Code, pipe `watch`+into the Monitor tool for real-time events.++## `janitor`: the screenshot cache++Every screenshot verb auto-pulls its PNGs to a local cache on the caller's machine+(`~/project/screenshots/adom-bridge/` when `~/project` exists, else+`~/.adom/screenshots/`; never `/tmp`), bucketed into `window/` and `screen/` with a+JSON sidecar per shot. The CLI-local `janitor` verb (no relay) keeps it bounded:++```bash+adom-bridge janitor                     # status: managed dirs, sizes, policy, last sweep+adom-bridge janitor '{"sub":"run"}'     # force a sweep now+```++A sweep also runs opportunistically at most once per 24h on any CLI call. Policy is+age + size capped, newest files kept; sidecars follow their PNG. Do not build your own+cleaner: verify with `janitor` status instead.++## Environment variables++| Variable | Effect |+|---|---|+| `ADOM_API` | Relay HTTP API base URL the CLI talks to (default `http://127.0.0.1:8766`). Point it at a proxied relay API to reach a remote relay directly. |+| `ADOM_TARGET` | Default `--target` value; the flag wins. |+| `ADOM_WS_PORT` / `ADOM_HTTP_PORT` | `serve` port overrides (defaults 8765 / 8766). |+| `ADOM_AUTH_TOKEN` | `serve` auth token. |+| `ADOM_JANITOR=0` | Disable the opportunistic cache sweep. |+| `ADOM_SHOTS_DIR` | Override the screenshot cache directory. |

@@ -0,0 +1,130 @@+---
+name: adom-bridge-demo-kit
+description: Run a guided on-screen demo or tour on the user's Windows desktop through Adom Bridge - the desktop_demo_panel transport (play/pause/next/back the USER controls), narration captions, and the branded ghost cursor, wired together into one pacing loop. Use when asked to give a demo, run a tour, walk the user through an app, or build a scripted show (altium_demo, kicad tour, fusion demo, or your own).
+---
+
+# The Adom Bridge demo kit: give the user a show they control
+
+A good demo has three surfaces, and Adom Bridge ships all three so you never
+invent your own:
+
+| Surface | Verb | What it does |
+|---|---|---|
+| **Transport panel** | `desktop_demo_panel` | A floaty glass PLAY / PAUSE / NEXT / BACK remote, bottom-right of the screen. The USER drives the pacing; you obey it. |
+| **Narration caption** | `desktop_caption` | Large click-through text at the bottom of the screen - your voice-over. One line per beat. |
+| **Pointer** | `desktop_cursor` / the auto cursor on `desktop_click` | The glowing teal Adom cursor that shows WHERE to look. Every synthetic click already glides it; label it with a few words. |
+
+The division of labor: the PANEL is the user's hand on the pacing, CAPTIONS are
+your narration, the CURSOR is your finger. Do not put narration on the panel
+(its stop line is a short label) and do not pace with sleeps the user cannot
+pause.
+
+## The pacing loop (the whole pattern)
+
+```text
+1. desktop_demo_panel {action:"show", id:"my-tour", title:"Fusion bridge tour",
+                       stops:["Open the library","Place the part","Run DRC"],
+                       stage:0, state:"playing",
+                       reason:"Guided tour of the fusion bridge, driven at the user's pace."}
+2. For each beat of the current stop:
+     - desktop_caption the narration line
+     - do the on-screen actions (clicks glide the branded cursor)
+3. BETWEEN beats: desktop_demo_panel {action:"poll", id:"my-tour"}
+     - state "paused"  -> HOLD. Keep polling (2-5s); do nothing on screen until "playing".
+     - event "next"/"back" -> the stage in the poll reply is ALREADY adjusted; jump your
+       script to that stop (do not also increment yourself).
+     - event "mute"/"unmute" (or muted:true on the reply) -> silence or resume your
+       NARRATION AUDIO (TTS, a music/voice track). The panel plays nothing itself -
+       the user is telling YOU to hush. Keep the visuals and captions going.
+     - event "stop"    -> the user ended the show and the panel already hid itself.
+       Clean up (close what you opened only if you opened it) and say goodbye in chat.
+     - no events, "playing" -> continue to the next beat.
+4. When YOUR script advances a stop: desktop_demo_panel {action:"show", id:"my-tour",
+   stage:<n>} - same id updates in place (title/stops/state/muted may be omitted;
+   they persist, so a stage-advance show never un-pauses or un-mutes).
+5. End of show: desktop_demo_panel {action:"hide", id:"my-tour"} + a closing caption.
+```
+
+**Poll cadence:** between every beat, and at least every few seconds during a
+long action. The panel queues presses (up to 64) so nothing is lost between
+polls - but a user who pressed PAUSE deserves the hold within a beat, not a
+minute later.
+
+**Instant push for LOCAL callers (optional):** if you run ON the same machine
+(an ah thread, a bridge process, a local agent) and hold a listener, pass
+`eventCallbackUrl` on show - a loopback http URL (`http://127.0.0.1:<port>/...`).
+Every button press is POSTed there immediately as
+`{id, button, at, state, stage, muted}`, so a pause lands the instant it is
+clicked instead of at your next poll. The push is best-effort and the poll
+queue stays the source of truth - keep polling as your backstop. Non-loopback
+URLs are refused (`callback_not_loopback`): this is a local wire, not web
+egress. A remote/relay caller cannot receive it (nothing on the user's machine
+is listening for them) - remote demos pace with poll alone, which is fine.
+
+## Rules that keep the show trustworthy
+
+- **`reason` is REQUIRED on show** (>= 10 chars). The user always sees who is
+  drawing on their screen. Same etiquette as captions.
+- **The panel never executes anything.** A button press only queues an event
+  for YOU to honor - it adds no permission surface, and a press you ignore is
+  a broken promise the user notices. Honor pause IMMEDIATELY.
+- **One panel at a time.** A `show` with a NEW id replaces the current panel;
+  the replaced id's undrained presses are dropped and your next poll says so
+  (`droppedEventsFor`). Keep ONE id for the whole show.
+- **Idle auto-hide (10 min).** If you stop showing/polling for 10 minutes the
+  panel hides itself - an abandoned overlay never lingers. Your poll keeps it
+  alive. The hide is announced like everything else: an `idle_hide` event goes
+  to your callback URL and the poll queue (it is not a user press - the panel
+  left the screen because YOU went quiet). Re-`show` to continue.
+- **The user can close it** (the gentle X, upper-right). Treat a vanished panel
+  + no stop event as "re-show once, and if it is closed again, end the show".
+- **Foreground etiquette:** warn with a caption BEFORE a window appears on
+  their screen, and prefer opening windows BEHIND the user's current one
+  (`desktop_set_window_state {state:"bottom"}`) unless the show is about that
+  window right now.
+
+## What the user sees (so you can describe it)
+
+Brand teal glass, DPI-scaled to match the OS text size. Title (their tour
+name), a stop line ("2/3 - Place the part"), a left-aligned BACK / PLAY-PAUSE /
+NEXT / MUTE row with hover + pressed feedback, and a gentle X in the corner.
+The mute speaker turns gray while muted. Draggable by its glass; clicks pass
+through the transparent feather around it. It NEVER steals focus - the user
+can keep typing elsewhere while it is up.
+
+Demos usually carry an audio track (ah demos narrate with one), so wire mute
+for real: when `muted` flips true, stop the sound within a beat and keep the
+show running silently; when it flips back, resume from where the narration is,
+not from the top.
+
+## Choosing stops
+
+Stops are chapters, not beats: 3-8 per show, named in the user's words
+("Open the library", not "Step 3"). Each stop should be safely enterable from
+BACK/NEXT - idempotent setup at the top of each stop makes jumps clean. A stop
+label renders inline as "n/total - label"; keep it under ~40 chars.
+
+## Testing your wiring without a human (the press hook)
+
+`{action:"press", id, button:"back"|"play"|"pause"|"next"|"mute"|"unmute"|"stop",
+reason:"..."}` mimics a press through the REAL push path - state and stage
+adjust, the event lands on the poll queue AND the callback POST - tagged
+`synthetic: true` on both wires so your script can tell its own injected
+events from the human's. Reason required. Use it to ralph-test your pacing
+loop end to end before a live show; never to fake user intent during one.
+
+## Minimal worked example
+
+```bash
+adom-bridge desktop_demo_panel '{"action":"show","id":"kicad-tour","title":"KiCad bridge tour","stops":["Open a schematic","Find a symbol","Run ERC"],"stage":0,"reason":"Three-stop guided tour of the KiCad bridge, driven at their pace."}'
+adom-bridge desktop_caption '{"text":"First stop: opening the demo schematic. Use the panel to pause me any time.","timeoutSec":8}'
+# ... do stop 0 ...
+adom-bridge desktop_demo_panel '{"action":"poll","id":"kicad-tour"}'
+# honor events, then advance:
+adom-bridge desktop_demo_panel '{"action":"show","id":"kicad-tour","stage":1}'
+```
+
+Bridges calling from inside their own process use the loopback direct API with
+the same JSON (`POST 127.0.0.1:24680/command {"command":"demo_panel", ...}`)
+and forward caller headers so the panel's attribution names the real thread
+(see the adom-bridge-sdk-callback skill).

@@ -0,0 +1,532 @@+---
+name: adom-bridge-direct-api
+description: Direct HTTP API on the adom-bridge GUI. Use when authoring a sibling Tauri app (Hydrogen, future Adom-family apps) on the same Windows machine that needs to send commands into adom-bridge without spawning the CLI binary or going through the WebSocket relay. Local-only (loopback bind).
+---
+
+# Direct HTTP API — discover via `~/.adom/direct-api-port`
+
+> **Port is no longer fixed.** As of v1.8.89, ab's direct API binds an OS-assigned ephemeral port whenever the fixed 47200..47209 range is unavailable (Windows HNS / Hyper-V silently reserves chunks of that range on most dev machines — see [PORTS.md](PORTS.md) for the full story). **Sibling apps MUST read the discovery file** `%USERPROFILE%\.adom\direct-api-port` (single-line `host:port`, e.g. `127.0.0.1:55272`) before any hardcoded probe. The legacy 47200..47209 scan stays as a back-compat fallback for older ab installs.
+
+Old: hardcoded `:47200`
+
+Sibling apps running on the same Windows host as adom-bridge can POST JSON commands directly into the running GUI process — no CLI process spawn, no WebSocket relay, no auth-token dance. The endpoint lives inside the GUI itself (loopback-only `127.0.0.1` bind, can't be reached off-box), uses the same dispatcher as the WebSocket path, and returns the same JSON shape — including every `_hint` field — that `adom-bridge <verb>` returns from the CLI.
+
+This skill is for **sibling-app authors** (Hydrogen's Tauri side, plus any future "Adom-family" desktop app). Docker callers should continue using the CLI or the WS proxy — those paths handle cross-machine transport and binary streaming, which the direct API intentionally doesn't.
+
+Shipped in adom-bridge v1.8.25+. Requires the adom-bridge GUI to be running on the host.
+
+## When to use this (vs. the CLI)
+
+| You are… | Use |
+|---|---|
+| A sibling Tauri app on the same Windows machine as adom-bridge, calling sync verbs like `server_add`, `bridge_list`, `hd_status`, `desktop_screenshot_window` | **Direct API.** One HTTP round-trip, ~5 ms, no process spawn. |
+| Inside Hydrogen's local Docker container, using the `adom-bridge` CLI | **Just use the CLI.** As of v1.8.27 it auto-detects the direct API at `host.docker.internal:47200` on every invocation and routes there transparently. Zero config in Hydrogen's container. The verb returns identical JSON to the cross-machine path. |
+| On the Windows host, running the `adom-bridge.exe` CLI directly | **Same — just use the CLI.** Auto-detects `127.0.0.1:47200` and routes through the direct API. ~60 ms warm per call vs ~150 ms for the relay path. |
+| Docker / Linux / cross-machine caller | The CLI `adom-bridge <verb>` (probe fails, falls through to the wss proxy → relay → GUI WS path — same behavior as v1.8.26 and earlier). |
+| A sibling app needing `pull_file`, `send_files`, or `shell_execute` | Spawn the CLI binary. The direct API refuses these with `errorCode:"cli_required"`. The CLI itself handles the fallback automatically when called. |
+
+### CLI auto-route (v1.8.27+)
+
+When the `adom-bridge` CLI binary runs in any of these contexts, it probes the direct API on the first verb invocation and caches the result for 30 seconds (in `/tmp/adom-direct-probe.json`):
+
+- **Discovery file (v1.8.31+, fastest path):** `~/.adom/direct-api-port` (Windows: `%USERPROFILE%\.adom\direct-api-port`). Contents are `host:port` (e.g. `127.0.0.1:47201`) and the CLI tries this first if present. The GUI writes the file at bind time and removes it at graceful shutdown.
+- **Probe order** (first 200 OK wins): `127.0.0.1:47200`, `host.docker.internal:47200`, `localhost:47200`
+- **Fallback scan (v1.8.31+):** if the discovery file is missing/stale AND the default candidates all fail, the probe scans `127.0.0.1:47201`..`47209`. Cheap — each closed port refuses connection in <5 ms on Windows loopback.
+- **Connect timeout**: 400 ms per candidate — fails fast when nothing's there
+- **Override**: `$ADOM_DIRECT_URL=off` forces relay-only; `$ADOM_DIRECT_URL=http://…:47209` skips the probe entirely and uses that URL; `auto` (default) does the probe
+
+The `ping` verb response now includes a `transport` field — `direct-http` or `relay-ws` — so you can confirm which path served the call. `pull_file`, `send_files`, and `shell_execute` always use the relay path (they have their own specialized streaming/approval flows). Everything else routes through the direct API when reachable.
+
+### Port-conflict auto-recovery (v1.8.31+, ephemeral fallback in v1.8.89+)
+
+The GUI never treats any individual port as fatal. Bind walk:
+
+1. **Probe first**: connect to the candidate port and send a `GET /health`. If anything responds within 1 s, a LIVE process owns the port — skip rather than coexist (SO_REUSEADDR would let us bind too, but the kernel would route incoming connections nondeterministically between us and the other listener).
+2. **Reuse-bind** with `SO_REUSEADDR` set via socket2 BEFORE bind. On Windows, this lets us claim a port held by a dead PID's zombie LISTEN socket — provided that prior process also used SO_REUSEADDR. (Pre-v1.8.31 zombies are stuck until reboot; v1.8.31+ zombies always release on the next launch.)
+3. **Walk the range** `47200`..`47209` on three categorical errors: `AddrInUse` (10048), `PermissionDenied` (10013 — Windows' code for "can't take over a non-REUSEADDR zombie"), or live-owner skip.
+4. **(NEW in v1.8.89) Ephemeral fallback**: if all of 47200..47209 fail (always WSAEADDRINUSE — which is what happens when HNS / Hyper-V has silently reserved the whole chunk; see [PORTS.md](PORTS.md) for why), bind `127.0.0.1:0` and let the OS pick. Whatever it picks goes to step 5. This case is COMMON on dev machines with Docker Desktop / WSL2 / Hyper-V VMs — the 47200..47299 chunk is reserved invisibly (doesn't show in netstat, doesn't show in excludedportrange, only fails-to-bind reveals it).
+5. **Write the chosen port** to `~/.adom/direct-api-port` so callers don't have to scan.
+6. **Report the bound address** in `/status.endpoint` — never a hardcoded constant.
+
+This handles all five practical cases:
+- **Zombie from v1.8.31+ adom-bridge** (was SO_REUSEADDR-bound) — new bind succeeds, takes over the same port.
+- **Zombie from older code OR force-killed third-party** (exclusive bind) — WSAEACCES on bind; walk to next port.
+- **Live owner** (Hydrogen's bridges, dev instance, anything responding) — probe detects, skip to next port.
+- **Empty port** — bind cleanly.
+- **HNS reserved the whole range** (v1.8.89+) — ephemeral fallback wins.
+
+### Graceful shutdown (v1.8.31+)
+
+When the GUI exits via the tray "Quit" menu (or any path that calls `app.exit(0)`), Tauri's `RunEvent::Exit` fires `direct_api::shutdown()` which:
+
+1. Sends a `oneshot` signal to the axum server
+2. `with_graceful_shutdown` stops accepting new connections and drains in-flight ones (~tens of ms)
+3. The TCP listener drops, releasing the port back to the OS *immediately*
+4. The discovery file is removed so callers don't connect to a port that's about to close
+
+This prevents zombie sockets on **clean exits**. For **force-kill** scenarios (`taskkill /F`, crash, BSOD), zombies can still exist temporarily — but the v1.8.31+ reuse-bind pattern means the NEXT launch can take over the same port instead of having to walk past it. Two layers of defense.
+
+## Endpoints
+
+### `GET /health`
+
+Cheap probe. Use to detect "is the GUI running" before falling through to the CLI fallback.
+
+```bash
+curl -sf http://127.0.0.1:47200/health
+# → {"ok":true,"service":"adom-bridge"}
+```
+
+Returns 200 + JSON when the GUI is up and the listener bound successfully. Connection refused (or timeout) means: GUI not running OR the port was already taken by something else when the GUI started. The CLI binary's `serve` mode does NOT bind 47200 — only the GUI does.
+
+### `GET /status`
+
+Service banner + version + capability inventory. Read once on sibling-app startup to learn the verb surface and the `cliRequired` list.
+
+```bash
+curl -sf http://127.0.0.1:47200/status
+```
+
+```json
+{
+  "ok": true,
+  "service": "adom-bridge",
+  "version": "1.8.25",
+  "schema": 1,
+  "transport": "direct-http",
+  "endpoint": "http://127.0.0.1:47200",
+  "directApi": {
+    "cliRequired": ["pull_file", "send_files", "shell_execute"],
+    "note": "Everything else is safe via direct POST /command. The listed verbs use binary streaming or multi-minute approval flows; spawn the `adom-bridge` CLI binary for those.",
+    "envelope": "{\"app\": <namespace>, \"command\": <verb>, \"args\": <args object>}",
+    "responseShape": "Identical to what `adom-bridge <verb>` returns — same `_hint` fields, same `success`/`ok`/`error` keys, same payload structure. The CLI and direct paths converge in `commands::handle_command`."
+  },
+  "wsl": {
+    "wslProcessCount": 18,
+    "wedged": false,
+    "_hint": null
+  },
+  "_hint": "POST /command with {app, command, args}. See https://wiki.adom.inc/adom/adom-bridge for the verb catalog."
+}
+```
+
+The **`wsl` block (v1.8.157+)** surfaces WSL health: `wslProcessCount` is a cheap Toolhelp snapshot of live `wsl.exe`; `wedged:true` (at/above 50) warns that orphaned/hung clients are piling up. When wedged, `_hint` points to `wsl_recover`. If a `wsl_exec`/`run_script` call returns `errorCode:"wsl_wedged"` (refuse-cap at 80), the machine is wedging — call `wsl_recover` (dry-run, then `{confirm:true}`) before retrying, rather than spawning more doomed clients. `wsl_recover` is reachable via `POST /command {app:"desktop", command:"wsl_recover"}` (the `desktop_` prefix is optional).
+
+The `schema` field is the contract version. v1 is the only one shipped. If `schema > 1` ever appears, expect a breaking change in the envelope/response shape and read this skill again.
+
+### `GET /commands` (v1.8.156+)
+
+Verb discovery — what `{app, command}` can a `/command` caller reach? A bridge delegating to ab no longer has to probe verb-by-verb and hit "Unknown desktop command".
+
+```bash
+curl -sf http://127.0.0.1:47200/commands
+```
+
+```json
+{
+  "ok": true,
+  "desktop": {
+    "app": "desktop",
+    "commands": ["list_windows","find_window","screenshot_window","taskbar","flash_window","activity_filter","run_script","process_list", "..."],
+    "note": "POST /command {app:\"desktop\", command}. The desktop_ prefix is OPTIONAL (desktop_taskbar == taskbar). Bad/missing args → the verb's _hint returns the arg schema."
+  },
+  "bridges": [{"name":"native-browser","verbPrefixes":["nbrowser_"],"verbs":["..."],"paused":false}],
+  "cliRequired": ["pull_file","send_files","shell_execute"],
+  "_hint": "Desktop verbs → app:\"desktop\" (prefix optional). Bridge verbs → app:\"dynamic\", command = full verb incl. prefix. cliRequired verbs need the CLI, not this HTTP API."
+}
+```
+
+Pair it with the per-verb schema hints: call a verb with missing args and its `_hint` returns `required`/`optional`/`example`. Between `/commands` (what exists) and the bad-args hint (how to call it), a fresh AI needs no prior knowledge.
+
+### `POST /command`
+
+Dispatches a verb. Body envelope (`app` is OPTIONAL as of v1.9.84 — inferred from the command):
+
+```json
+{
+  "command": "server_add",
+  "args": { "name": "hydrogen-workspace", "url": "ws://localhost:8765", "autoConnect": true }
+}
+```
+
+#### Full verb surface + cross-ab (v1.9.84)
+
+A caller (a **bridge** especially) reaches **every dispatchable verb** here, not just `desktop_*` — same dispatcher as the CLI/WS path, identical JSON back (`_hint`/`errorCode`/`statusVerb`). `GET /commands` lists the full set to capability-probe.
+
+- **`app` is optional** — inferred (`kicad_*`→kicad, `fusion_*`→fusion360, `pup_*`→browser, `hd_*`→hd, `aps_*`→aps, any installed bridge's prefix→dynamic, else desktop). Pass `app` explicitly to override.
+- **Top-level verbs now reachable:** `notify_user` (toast → returns `{action:"displayed"}`), `notify_response`, `targets` (list the OTHER ABs on the relay), `ping` (this ab's liveness+version), plus `bridge_list`/`bridge_info`/`refresh_bridges`/`runtimes`/`status`.
+- **`target` (cross-ab):** add `"target": "<clientName>"` (from `targets`) or `"all"` to route the call to a PEER ab via the relay — e.g. a bridge on a VM notifies the user on their laptop. `"self"`/`"local"`/absent = local. `"attended"` → `errorCode:attended_unresolved` (not built yet; use a concrete clientName).
+- **`X-Adom-Bridge-Token` header = attribution + caller-identity migration, not approval.** A bridge MAY send its spawn-time `ADOM_BRIDGE_TOKEN` env value; ab then badges the call "bridge" in the Activity Log and applies the temporary bridge exemption from `caller_identity_required`. A bridge is still trusted-by-install (127.0.0.1-bound; PERMISSION_MODEL.md), so the token never controls Tier-2 approval. A stale/wrong token is warned once and treated like an omitted token: the call is badged `direct:<port>` and an identified callback continues, while an unidentified callback receives the normal teaching refusal. The full surface (incl. `write_file`/`run_script`) runs ungated for any local caller; only the remote relay origin is approval-gated.
+
+Example — a bridge fires a toast to the user's laptop while running on a VM:
+```bash
+curl -s -X POST "$ADOM_DIRECT_API_URL/command" -H 'Content-Type: application/json' \
+  -H "X-Adom-Bridge-Token: $ADOM_BRIDGE_TOKEN" \
+  -d '{"command":"notify_user","target":"AdomLapper","args":{"title":"Action needed","body":"Approve the Chrome dialog on your laptop"}}'
+```
+
+Plain single-ab envelope (unchanged, `app` still honored when provided):
+
+```json
+{
+  "app": "desktop",
+  "command": "server_add",
+  "args": { "name": "hydrogen-workspace", "url": "ws://localhost:8765", "autoConnect": true }
+}
+```
+
+Response is the verb's normal payload (200 OK), e.g.:
+
+```json
+{
+  "ok": true,
+  "success": true,
+  "name": "hydrogen-workspace",
+  "url": "ws://localhost:8765",
+  "id": "...",
+  "connected": true,
+  "created": true,
+  "_hint": "Server registered. Relay commands for this container now route through adom-bridge. Use server_list to see all connections."
+}
+```
+
+#### Error responses
+
+| HTTP | When | Body shape |
+|---|---|---|
+| `400 Bad Request` | Envelope missing `app` or `command` | `{ok:false, error, _hint}` |
+| `412 Precondition Failed` | Verb is in `cliRequired` list | `{ok:false, errorCode:"cli_required", _hint}` |
+| `500 Internal Server Error` | Handler dropped the response channel (bug) | `{ok:false, errorCode:"handler_silent", _hint}` |
+| `504 Gateway Timeout` | Handler didn't respond within the per-verb timeout (see below) | `{ok:false, errorCode:"timeout", _hint}` |
+
+Every error carries an actionable `_hint` and (for non-400s) a stable `errorCode` string you can branch on.
+
+#### Per-verb timeouts (v1.8.31+)
+
+The 504 timeout is **per-verb**, not a hardcoded 120s ceiling:
+
+| Verb category | Default timeout |
+|---|---|
+| `walk_cloud_tree`, `search_cloud_files` | **620 s** (10+ min — cloud trees can be hundreds of folders @ ~1 fps) |
+| `export_step`/`iges`/`sat`/`stl`/`3mf`/`usdz`/`obj`/`f3d`/`fbx`/`skp`/`source`/`eagle_source` | 320 s |
+| `export_gerbers` | 200 s |
+| `export_dxf`/`dwg` | 140 s |
+| `drc`, `erc` | 180 s |
+| `bridge_install`, `fusion_start` | 300 s |
+| Everything else | 120 s |
+
+Override per-call by passing `args.timeout` (seconds), clamped to a 1800 s ceiling:
+
+```json
+{
+  "app": "fusion",
+  "command": "search_cloud_files",
+  "args": {
+    "query": "cosmiic",
+    "recursive": true,
+    "maxFolders": 1000,
+    "searchTimeout": 1500,
+    "timeout": 1700
+  }
+}
+```
+
+The CLI dispatcher honors `args.timeout` the same way, so the two paths stay symmetric.
+
+## Update endpoints (v1.8.134+) — Hydrogen-driven embedded auto-update
+
+ab owns its own updater (fetch → SHA-verify → stage). Hydrogen does **not** download or
+install ab's bytes — it reads ab's update state and, at a safe moment, "clicks
+ab's Update button" via `POST /update/apply`. The contract is intentionally tiny
+and is meant to generalize to other Hydrogen-bundled children (e.g. the Adom screensaver):
+`{ update_status, apply, busy }`.
+
+### `GET /update/status`
+
+```bash
+curl -sf http://127.0.0.1:47200/update/status
+```
+
+```json
+{
+  "current_version": "1.8.133",
+  "available_version": "1.8.134",
+  "update_ready": true,
+  "state": "staged",
+  "busy": false
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `current_version` | The running ab version. Plain dotted semver; compare component-wise, numeric, never-downgrade. |
+| `available_version` | Latest version ab knows about from its manifest (`null` until the first check). May equal `current_version` when on latest. |
+| `update_ready` | `true` **only** when a newer installer is already downloaded **+ SHA256-verified + staged on disk** — appliable with **no further network**. Equivalent to `state == "staged"`. |
+| `state` | One of `idle \| checking \| downloading \| staged \| applying`. |
+| `busy` | `true` while ab is mid-operation it shouldn't be interrupted for — an in-flight screenshot, a file transfer, or a bridge (kicad/fusion/puppeteer) command awaiting its reply. **Hydrogen should defer the apply until `busy == false`.** (A screen-share/getDisplayMedia source is reserved for when ab adds that feature.) |
+
+`state` machine: `idle` → `checking` (a manifest check is running) → `downloading`
+(fetching + verifying the installer) → `staged` (verified on disk; `update_ready=true`)
+→ `applying` (apply triggered; ab about to restart). A failed check never un-stages a
+previously-staged update.
+
+### `POST /update/apply`
+
+Applies the already-staged update — the programmatic equivalent of the user clicking
+"Update". No request body.
+
+```bash
+curl -sf -X POST http://127.0.0.1:47200/update/apply
+```
+
+```json
+{ "ok": true, "applying": true }
+```
+
+- **Only ever applies what ab itself staged + verified.** If nothing is staged, returns
+  HTTP 409 `{ "ok": false, "applying": false, "error": "no update staged …", "_hint": … }`.
+  Call `POST /update/check` first and poll `/update/status` until `update_ready=true`.
+- **Embedded-aware:** no modal / blocking UI. ab returns this JSON **promptly** (before it
+  restarts), runs the staged installer, then exits cleanly ~1.5 s later.
+- **Comes back in embedded mode automatically.** ab's embedded marker on disk persists
+  across the restart (the exit hook only drains the direct-API socket — it doesn't delete
+  the marker), so the relaunched ab re-enters embedded mode via the marker + the Hydrogen-liveness
+  probe. Hydrogen's normal adopt (`POST /embedded/enter`) on the next supervisor tick re-asserts it
+  idempotently.
+
+#### Restart handshake — Hydrogen MUST suspend respawn for the apply window
+
+Because the apply runs the NSIS installer **over the running ab exe**, Windows' mmap lock on
+the running image means the file replacement only succeeds once ab has fully exited. **If Hydrogen's
+supervisor respawns ab during the install window, it re-locks the exe and the replacement
+silently no-ops** (ab comes back on the OLD version). So:
+
+1. `GET /update/status` → wait for `update_ready == true && busy == false`.
+2. `POST /update/apply` → on `{ applying: true }`, **stop respawning ab** (suspend the ~5 s
+   health-respawn) for ~60 s.
+3. ab exits → the staged installer replaces files → relaunches ab (installer POSTINSTALL).
+   ab re-embeds via its marker.
+4. Hydrogen polls `GET /update/status` (or `/health`/`/buildinfo`); when ab answers again with
+   `current_version ==` the new version, resume normal supervision + re-adopt
+   (`POST /embedded/enter`).
+
+Hydrogen initiated the apply, so Hydrogen already knows the restart is intentional — treat ab's
+disappearance in this window as expected, not a crash.
+
+### `POST /update/check`
+
+Force a manifest check now. If a newer version is found, ab stages it **in the background**;
+this call returns the `/update/status` shape promptly (poll it until `staged`). No request body.
+
+```bash
+curl -sf -X POST http://127.0.0.1:47200/update/check
+```
+
+Returns the same JSON shape as `GET /update/status`.
+
+### Standalone vs embedded
+
+- **Standalone ab:** the normal user-facing "Update available → Update" footer button +
+  flow are unchanged. `auto` mode still silently self-updates; `prompt` shows the banner;
+  `off` disables checks (and staging).
+- **Embedded ab:** ab checks + **stages** on its own (so `update_ready` becomes true for Hydrogen)
+  but **never auto-applies** — Hydrogen owns the apply timing via `POST /update/apply`. The
+  embedded apply path never pops its own restart UI.
+
+## What the user sees in the GUI Activity Log
+
+Each `POST /command` call shows up in adom-bridge's Activity Log panel with a `direct:<actual-port>` badge (for example, `direct:24680`) plus the verb's normal event tag (`desktop`, `kicad`, `hd`, etc.). A current bridge token changes that source badge to `bridge`; an omitted or stale token uses the direct-port badge. This is visually distinct from the `localhost` badge attached to WS-relay traffic going through the localhost dev server at `ws://localhost:8865`.
+
+At startup, a single `direct-api` event-tagged entry reports the actual loopback address (normally `http://127.0.0.1:24680`) and carries the matching direct-port badge. If the bind ever fails, the user sees a corresponding attempted-port error entry — no silent failure.
+
+## Trust model
+
+- **Loopback-only bind.** The listener binds `127.0.0.1`, never `0.0.0.0`. Off-machine HTTP requests can't reach it.
+- **No token required.** Anything on the user's box can send commands. The loopback bind is the boundary. If you need stricter isolation, the WS path's auth-token handshake is what to use.
+- **Same verb surface as the WS path.** Every authorization check that lives inside a verb handler (shell auto-approve, file-path sandboxing, bridge-paused refusal) applies equally to direct calls — the dispatcher is the same code.
+
+## Reference integration: Hydrogen startup
+
+This is the canonical pattern Hydrogen uses to register its container relay with adom-bridge at boot.
+
+### Rust (Hydrogen's `src-tauri/src/lib.rs` or equivalent)
+
+```rust
+use serde_json::json;
+use std::time::Duration;
+
+const ADOM_HEALTH: &str = "http://127.0.0.1:47200/health";
+const ADOM_COMMAND: &str = "http://127.0.0.1:47200/command";
+
+async fn register_with_adom_bridge(workspace_name: &str, relay_url: &str) -> Result<(), String> {
+    // 1. Cheap probe — is adom-bridge running and listening?
+    let client = reqwest::Client::builder()
+        .timeout(Duration::from_secs(2))
+        .build()
+        .map_err(|e| format!("client init: {e}"))?;
+
+    let healthy = client
+        .get(ADOM_HEALTH)
+        .send()
+        .await
+        .ok()
+        .filter(|r| r.status().is_success())
+        .is_some();
+
+    if !healthy {
+        // adom-bridge not running. Either tell the user to launch it,
+        // or shell out to the CLI as the legacy fallback. Don't block
+        // Hydrogen startup.
+        log::warn!("adom-bridge not reachable on 127.0.0.1:47200 — relay will not be auto-registered");
+        return Ok(());
+    }
+
+    // 2. POST the server_add command.
+    let resp = client
+        .post(ADOM_COMMAND)
+        .timeout(Duration::from_secs(10))
+        .json(&json!({
+            "app": "desktop",
+            "command": "server_add",
+            "args": {
+                "name": workspace_name,
+                "url": relay_url,
+                "autoConnect": true,
+            }
+        }))
+        .send()
+        .await
+        .map_err(|e| format!("POST /command: {e}"))?;
+
+    let body: serde_json::Value = resp.json().await.map_err(|e| format!("parse: {e}"))?;
+
+    if body.get("ok").and_then(|v| v.as_bool()) == Some(true) {
+        log::info!(
+            "adom-bridge registered: name={workspace_name}, url={relay_url}, _hint={}",
+            body.get("_hint").and_then(|v| v.as_str()).unwrap_or("")
+        );
+        Ok(())
+    } else {
+        Err(format!("adom-bridge refused: {body}"))
+    }
+}
+```
+
+### TypeScript (Hydrogen's frontend, if it ever calls directly)
+
+```typescript
+async function registerWithAdomBridge(name: string, url: string): Promise<boolean> {
+  // probe first
+  const health = await fetch('http://127.0.0.1:47200/health', { signal: AbortSignal.timeout(2000) }).catch(() => null);
+  if (!health?.ok) return false;
+
+  const resp = await fetch('http://127.0.0.1:47200/command', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    signal: AbortSignal.timeout(10_000),
+    body: JSON.stringify({
+      app: 'desktop',
+      command: 'server_add',
+      args: { name, url, autoConnect: true },
+    }),
+  });
+  const body = await resp.json();
+  return body.ok === true;
+}
+```
+
+## Cleanup at shutdown
+
+Mirror the registration with a `server_remove`:
+
+```bash
+curl -X POST http://127.0.0.1:47200/command \
+  -H 'Content-Type: application/json' \
+  -d '{"app":"desktop","command":"server_remove","args":{"name":"hydrogen-workspace"}}'
+```
+
+If adom-bridge has already exited, the connection refuses — that's fine, the server entry is stale either way. Treat shutdown registration cleanup as best-effort.
+
+## Embedded-mode integration (Hydrogen bundling ab, v1.8.42+)
+
+When Hydrogen bundles ab, the direct API is the channel for Hydrogen's tray menu items and runtime control. Hydrogen spawns ab with `--embedded --start-hidden --relay-url ... --session-token ...`, then drives it via these direct-API calls:
+
+| Hydrogen action | direct-API envelope |
+|---|---|
+| "Open Adom Bridge" tray menu item | `{app:"desktop", command:"window_show"}` |
+| Hide ab's window again | `{app:"desktop", command:"window_hide"}` |
+| "Connect All" / "Disconnect All" tray items | `{app:"desktop", command:"connect_all"}` / `disconnect_all` |
+| Hydrogen's "Quit" menu (cascade-stops ab) | `{app:"desktop", command:"shutdown"}` |
+| Hydrogen sign-out propagation | `{app:"desktop", command:"logout"}` |
+| Introspect embedded state | `{app:"desktop", command:"embedded_status"}` |
+| Force permanent shell auto-approve | `{app:"desktop", command:"set_shell_auto_approve", args:{permanent:true}}` |
+
+`embedded_status` returns `{embedded, owner, source, pendingRelayUrl, pendingRelayName, startHidden, markerPath, markerExists}` — useful for Hydrogen's tray to know whether ab already booted embedded or it's running standalone.
+
+```typescript
+// Hydrogen's tray-click handler — example
+async function openAdomBridge() {
+  await fetch('http://127.0.0.1:47200/command', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ app: 'desktop', command: 'window_show' }),
+  });
+}
+```
+
+Note: Hydrogen typically calls `set_shell_auto_approve {permanent: true}` only as a recovery path — ab already defaults to permanent at embedded boot. Use it when toggling user-controlled preferences (e.g. an Hydrogen setting like "Auto-approve ab shell commands ON/OFF").
+
+## What about verbs not in the directApi list?
+
+The `cliRequired` array in `GET /status` lists the verbs that need the CLI binary. Anything not in that list works over the direct API. The dispatcher is the same code; if a verb works via `adom-bridge <verb>` it works via direct POST.
+
+### Mapping CLI verb → direct-API envelope
+
+**The prefix-stripping rule varies per namespace.** Easiest mental model: look at the CLI's `cli/src/commands.rs` dispatch line for the verb you want. Whatever string it passes as the second arg of `relay::desktop_command(app, command, ...)` is exactly what your direct-API envelope's `command` field should be.
+
+**v1.8.153+: for `app:"desktop"` the `desktop_` prefix is OPTIONAL — POST the public verb name as-is.** A bridge delegating via `ADOM_DIRECT_API_URL/command` can send the exact verb it knows (`desktop_taskbar`, `desktop_flash_window`, `desktop_list_windows`, `desktop_find_window`, `desktop_screenshot_window`, `desktop_record_window_start/stop/status`) OR the stripped form (`taskbar`, …) — both dispatch. (Before 1.8.153 the dispatch arms were unprefixed, so `desktop_taskbar` returned "Unknown desktop command" while `run_script` worked — that asymmetry is gone.)
+
+| `app` value | What goes in `command` | Examples (CLI verb → direct envelope) |
+|---|---|---|
+| `desktop` | public verb name; `desktop_` prefix optional (v1.8.153+) | `desktop_taskbar` → `{app:"desktop", command:"desktop_taskbar"}` (or `"taskbar"`); `server_add` → `{app:"desktop", command:"server_add"}` |
+| `kicad` | **stripped** — drop the `kicad_` prefix | `kicad_open_board` → `{app:"kicad", command:"open_board"}` |
+| `fusion360` | **stripped** — drop the `fusion_` prefix | `fusion_start` → `{app:"fusion360", command:"launch"}` (note: also the verb name shifts internally) |
+| `browser` | **kept** — pup bridge dispatches on the full name | `browser_open_window` → `{app:"browser", command:"browser_open_window"}` |
+| `hd` | **stripped** — drop the `hd_` prefix | `hd_status` → `{app:"hd", command:"status"}` |
+| `dynamic` | full verb name with third-party bridge prefix preserved | (dispatcher routes by prefix) |
+
+Common direct-safe verb groups:
+
+| Namespace | Examples | Notes |
+|---|---|---|
+| `desktop` | `server_add`, `server_remove`, `server_list`, `bridge_list`, `bridge_install`, `bridge_pause`, `bridge_resume`, `desktop_list_windows`, `desktop_screenshot_window`, `desktop_open_url`, `set_shell_auto_approve` | All sync, no prefix stripping. |
+| `hd` | `status`, `eval`, `log`, `screenshot`, `build`, `build_frontend`, `build_rust`, `build_status`, `build_log`, `build_tail`, `launch`, `stop`, `restart` | `build*` returns instantly with `{pid, logPath}`; poll `build_status` or `build_tail` for progress. |
+| `kicad` | `list_versions`, `open_board`, `open_schematic`, `run_drc`, `lint_board`, `install_symbol`, ... | Multi-version-aware. |
+| `fusion360` | `launch`, `export_step`, `walk_cloud_tree`, `window_info`, `get_app_state`, ... | 50+ verbs. |
+| `browser` | `browser_open_window`, `browser_navigate`, `browser_screenshot`, `browser_eval`, `browser_click`, `browser_record_start` | Per-tab. **Keep the prefix.** |
+
+## Failure modes & retry
+
+The direct API doesn't auto-retry. Sibling apps should:
+
+1. **Probe `/health` before any `/command`** so a missing GUI is a clean "not available" branch, not a noisy 10-second timeout on every dispatch.
+2. **Per-request timeouts ≥ the verb's natural duration.** Most verbs are sub-second; `hd_build*` returns in <2 s; `bridge_install` can be 30 s for a large zip. Pick the timeout based on the verb you're calling.
+3. **Treat 504 timeouts as "unknown state, ask later"** rather than retrying blindly. A successful retry on a 504 might double-register a server or double-install a bridge.
+4. **Read the `_hint` and `errorCode` fields on every error response.** They're machine-friendly: `cli_required`, `timeout`, `handler_silent`, plus whatever the verb's handler emits (`bridge_not_found`, `binary_missing`, etc.).
+
+## Version skew
+
+If `GET /status` returns `version < 1.8.25` OR fails entirely OR `schema` is missing, the direct API isn't present (older GUI). Fall back to spawning the CLI binary. The CLI has been the supported integration path since v1.7.x; everything that works via the direct API also works via the CLI, just slower.
+
+## Why a separate port from the WS relay's 8766?
+
+- **Different transport, different trust model.** 8766 is the relay's HTTP endpoint, which goes through a WS bridge to the GUI and gates non-CLI User-Agents. 47200 is direct to the GUI, no auth, loopback-only.
+- **Different process lifecycle.** 8766 needs `adom-bridge serve` running (a separate process). 47200 is inside the GUI — if the GUI is running, 47200 is up.
+- **No risk of breaking Docker.** Docker callers keep using 8766 + the WS proxy. Sibling apps get 47200. They don't fight for the same port or auth scheme.
+
+## See also
+
+- [`README.md`](../README.md) — feature list
+- [`skills/SKILL.md`](SKILL.md) — full verb catalog (the entries Docker callers read)
+- [`src-tauri/src/direct_api.rs`](../src-tauri/src/direct_api.rs) — implementation
+- [Adom Wiki — apps/adom-bridge](https://wiki.adom.inc/adom/adom-bridge) — public verb reference

@@ -0,0 +1,87 @@+---+name: adom-bridge-discovery+user-invocable: false+description: "Reaches the user's Windows/Mac laptop desktop from this container via adom-bridge — run commands & scripts on the laptop, list/kill processes, restart apps (e.g. Explorer), desktop/app-window screenshots, send/pull files, notifications, list/focus/flash windows, RDP tunnels. Also launches and drives KiCad (schematics/boards/symbols/footprints, DRC, library install, 3D viewer, automation) and Fusion 360 (.f3d/.f3z, import/export STEP/GLB/.lbr, BOM/parameters, Fusion API). Also covers Puppeteer/pup real-Chrome automation (pup_screenshot, pup_eval, pup_navigate, multi-session profiles, ralph-loop), WSL distro control + golden-image bakes (wsl_exec, wsl_exec_async, wsl_import/export/unregister), the relay server (adom-bridge serve), and connection setup. Trigger words: run command on laptop, run on my pc, restart explorer, restart a program, kill a process, list processes, taskkill, screenshot laptop/desktop/windows/fusion/kicad, list windows, focus window, send file to laptop, pull file from laptop, desktop notification, launch KiCad, open in KiCad, run DRC, launch Fusion, import/export STEP, export GLB/lbr, Fusion API, pup, puppeteer, real Chrome, browser automation, flash taskbar, open URL on desktop, RDP, tunnel, WSL, golden image, adom-bridge, bridge to my pc, windows app, KiCad bridge, Fusion bridge."+---++# adom-bridge — discovery & install++**This skill is a pointer.** When any trigger fires, confirm `adom-bridge` is installed (install from the wiki if not), make sure the relay is up, then **discover the exact verb at runtime** — do NOT guess from memory and do NOT rely on `--help`.++## 1 — Check it's installed + the relay is up++```bash+adom-bridge --version          # path + version, e.g. adom-bridge 1.8.163 (<sha>, built …)+adom-bridge ping               # {echo:"pong", status:"connected"} == the laptop is reachable+```++If `adom-bridge` isn't found → **§4 install**. If `ping` doesn't say `connected`, the relay isn't serving — start it: `adom-bridge serve --supervise` (v1.9.168+ — detaches + self-heals so it survives your session; a plain `serve &` dies when the session is torn down and leaves every connected desktop in an HTTP 500 reconnect loop). Then re-`ping`.++### Connecting a desktop for the FIRST time — run `setup_desktop`, don't hand-build JSON++If no desktop is connected yet (`adom-bridge targets` shows none) and you need to set one up, **run `adom-bridge setup_desktop`** (aliases: `connect`, `setup`, `connect_info`). It auto-detects this container's public relay URL and hands you everything. **Do NOT assemble the connection JSON yourself** — guessing the URL/fields is the #1 setup failure (wiki issue #8).++**PREFERRED — zero paste (the modern path):** `setup_desktop` returns a ready-to-run **`register_command`**. Run it — it's `adom-bridge register_container` with the name + URL filled in, and it writes this connection into the **user's Adom account** (their cloud profile). Then the user just **installs Adom Bridge and signs in with their Adom account**, and the connection appears in their list and auto-connects — no JSON paste at all. (`register_container` needs an Adom cloud container — it uses the mounted account token; it returns `ok:false` on a non-Adom box.)++**FALLBACK — paste-JSON:** if `register_container` returns `ok:false` (not an Adom cloud container, or the user won't sign in), have the user paste the `server_config` JSON that `setup_desktop` returned into ab's Connections → "Paste server JSON to add" box.++Either way, start the relay here so the desktop has something to dial: `adom-bridge serve --supervise`. Verify with `adom-bridge targets`.++## 2 — ⭐ DISCOVER THE VERB: `adom-bridge commands` (NOT `--help`)++This is the step that's most often skipped, and skipping it is why calls get hand-rolled with `shell_execute` and fumble. **`adom-bridge --help` only lists `serve` / `install`** — every real capability is a *dynamic verb* forwarded to the laptop, and the authoritative, machine-readable catalog (200+ verbs, each with args + return shape + a `_hint`) is:++```bash+adom-bridge commands            # full verb catalog (categories → verbs → args/returns)+adom-bridge status              # laptop state (installed apps, WSL health, …) — also surfaces the catalog+```++**Always check `commands` before reaching for `shell_execute`.** There is almost certainly a structured verb that takes typed args, so you never hand-quote a command through JSON → shell. A few you'll want often:++| Want to… | Use (structured — no quoting) | NOT |+|---|---|---|+| list processes | `process_list {"nameContains":"explorer"}` | `shell_execute "tasklist \| findstr …"` |+| kill a process | `process_kill {"name":"explorer.exe"}` (or `{"pid":N}`) | `shell_execute "taskkill /f /im …"` |+| start an app | `launch_process {"path":"explorer.exe"}` / `launch {…}` | `shell_execute "start …"` |+| run a multi-line / quoted script | `run_script {"interpreter":"powershell\|cmd\|bash","scriptB64":"<base64>"}` | `shell_execute` with nested quotes |+| run inside a WSL distro | `wsl_exec {"distro","user","scriptB64"}`; multi-minute → `wsl_exec_async` + poll `wsl_job_status` | — |+| screenshots / windows | `desktop_list_windows`, `desktop_screenshot_window {"hwnd":N}`, `desktop_find_window`, `desktop_bring_to_front` | — |+| move files | `send_files` (→ laptop), `pull_file` (← laptop) | — |++> **Example — "restart Explorer because the taskbar icons are gone":** `process_kill {"name":"explorer.exe"}` → `launch_process {"path":"explorer.exe"}` → `process_list {"nameContains":"explorer"}` to confirm. No `taskkill`/`tasklist` quoting. (`shell_execute` is the escape hatch for things with no verb yet — `cmd /C`; reserve it for that.)++**Reading any result:** every verb returns a uniform **`status`** (`ok` | `timeout` | `busy` | `error`) + **`durationMs`**, alongside `exitCode`/`stdout`/`stderr` for exec verbs. So an empty `stdout` with `status:ok` is a real empty-output success — NOT a timeout. `timeout`/`busy` carry a recovery `_hint`. Multi-ab relay: if you get `status:error` / `ambiguous_target`, pass `--target <name>` (list them with `adom-bridge targets`).++## 3 — Multi-distro / long ops++For golden-image work and any multi-minute command, use the **detached job** verbs (return a `jobId` instantly, then poll `wsl_job_status`) instead of a sync call that would time out: `wsl_import` / `wsl_export` / `wsl_unregister` / `wsl_exec_async`, and `launch_process` for a general long-running process. `wsl_recover` reaps a wedged WSL. See `adom-bridge commands` for exact args.++## 4 — Install (if missing or stale)++The canonical install is the adompkg (bundles the Linux CLI **and** the skill set, which symlink into `~/.claude/skills/`):++```bash+adompkg install adom/adom-bridge     # → ~/.local/bin/adom-bridge + the adom-bridge-* skills+adom-bridge --version                # confirm+```++`adom-bridge status` reports the latest published version; if your local CLI is older, re-run `adompkg install adom/adom-bridge` to refresh the binary **and** the skills atomically. (Wiki page: `https://wiki.adom.inc/adom/adom-bridge`.) **If you hand-installed only the binary, you won't have the skill set — re-run the adompkg install so the discovery/main/pup/kicad/fusion/direct-api/installer skills land too.**++## 5 — What you get once installed++`adompkg install` lays down sibling skills that document the features in depth — they appear in future skill searches:++| Skill | Covers |+|---|---|+| `adom-bridge` (main) | the full verb reference + shell/process/file/window/WSL/tunnel patterns, status+durationMs result shape |+| `adom-bridge-pup` | Puppeteer real-Chrome automation (pup_open_window/navigate/screenshot/eval, multi-session profiles) |+| `adom-bridge-kicad` | KiCad bridge (open schematics/boards, DRC, library install, 3D viewer, automation) |+| `adom-bridge-fusion` | Fusion 360 bridge (.f3d/.f3z, STEP/GLB/.lbr import-export, BOM/params, Fusion API) |+| `adom-bridge-direct-api` | the loopback HTTP API for sibling apps (Hydrogen) |+| `adom-bridge-installer` | invoking the Windows installer (silent/NOLAUNCH) |++But you don't need to read those to act — **`adom-bridge commands` is always the live source of truth** for what verbs exist right now.++## 6 — Why this skill exists++adom-bridge is its own repo with its own release cadence; the deep feature docs ship with the binary (so a binary release doesn't force a gallia release). This skill is the stable, always-present entry point — its one job is to get you to `adom-bridge commands`, the runtime catalog, instead of guessing.

@@ -0,0 +1,154 @@+---
+name: adom-bridge-embedded
+description: Adom Bridge's EMBEDDED mode under Hydrogen — what it means when Hydrogen owns ab, the lifecycle contract (ab stays up; exit when Hydrogen exits is opt-in flag-only), and embedded permissions in the CURRENT (v1.9.191) model where AB OWNS APPROVALS and MIRRORS each request to Hydrogen (Hydrogen posts decisions to /permission/resolve, reads /permission/state; the old auto_approve/forward-to-hd contract is gone), inspecting Hydrogen with hd_status and the hd_ verb family, and the read-only Hydrogen-managed relay entry. Use when reasoning about embedded vs standalone behavior, why ab survived (or should survive) an Hydrogen crash, why a gated relay command shows an ab dialog (and mirrors to Hydrogen), or how to drive/inspect Hydrogen. Note: Hydrogen's own setup commands over the loopback direct API are trusted-by-transport and never prompt.
+---
+
+# Adom Bridge embedded mode (under Hydrogen)
+
+## What embedded mode is
+
+Hydrogen bundles the signed ab NSIS installer, silent-installs it,
+and at runtime spawns ab as its child:
+
+```
+adom-bridge.exe --embedded --start-hidden --relay-url ws://127.0.0.1:8765 --relay-name hydrogen-desktop [--session-token <hd token>]
+```
+
+While embedded:
+
+- ab's window is hidden and **ab hides its tray icon** — Hydrogen is the app the human
+  sees. ab keeps serving everything (relay, direct API on 127.0.0.1:47200,
+  bridges) the whole time.
+- The taskbar identity flips: ab's window swaps from the muted standalone
+  "Adom Bridge" tile to the vivid teal **"Adom Bridge Hydrogen Embedded"** tile
+  (an AUMID flip on the main window — name AND tile change in about 1s, no
+  restart). The tile is how you tell at a glance who is driving.
+- ab writes an `embedded.json` marker (with `entered_via`) so a restart
+  re-embeds if Hydrogen is still alive.
+- Hydrogen injects a relay-back server entry tagged `added_by:"hd-spawn"` (see the
+  read-only rule below).
+
+Entry paths: `POST /embedded/enter` on the direct API, or the `--embedded`
+launch flag. Hydrogen polls `GET http://127.0.0.1:47200/health` after spawning.
+
+## The lifecycle contract (AB_LIFECYCLE.md, on one page)
+
+1. **ab stays up.** It is the recovery channel for the machine: if ab exited
+   whenever Hydrogen exited, one bad Hydrogen exit would leave the box unreachable to any
+   remote agent (no log reads, no relaunch, no rollback).
+2. **The ONLY thing that exits ab is an explicit shutdown** —
+   `desktop_shutdown` / `POST /command {"command":"shutdown"}`, or the user
+   closing ab themselves.
+3. **"Embedded" is a display state, not a lifecycle.** Hydrogen gone means ab drops
+   the costume and reverts to a normal standalone tray app.
+
+What happens when Hydrogen goes away:
+
+| How Hydrogen goes away | What ab does |
+|---|---|
+| Graceful: Hydrogen sends `POST /embedded/release` before stopping | Revert to standalone (tray back, relay preserved). Behaves this way since v1.8.77 regardless of how ab entered embedded. |
+| Ungraceful: Hydrogen's GUI crashes or is killed, no release sent | The `embedded_monitor` (10s probes, 3-miss debounce, ~30s) notices and reverts to standalone. Same end state. |
+| A tree-kill takes Hydrogen's whole process group | ab dies WITH Hydrogen because it is Hydrogen's direct child process. This is the OS killing a child, NOT a lifecycle rule firing. Check for the tree-kill before blaming any ab logic. |
+
+Reverting (`revert_to_standalone`) shows the tray again and **keeps the WS
+connection and the hd-spawn server entry** — the supervisor reconnects with
+backoff, so a remote caller sees `status=reconnecting`, never a vanished row
+(Hydrogen's relay lives in a WSL2 container that can outlive Hydrogen's GUI).
+
+**Exit-with-ah is opt-in, flag-only (v1.9.165).** The only way to make ab
+disposable is the spawner passing `--exit-when-hd-exits` on the command line.
+Hydrogen does not pass it, so in practice ab always survives. There is no config key
+(the old `config.exit_when_hd_exits` is inert) and no Settings checkbox. The
+one flag-gated exit lives in `embedded_monitor::transition_to_standalone`.
+
+Forensics: both transitions write to `startup.log` (`EXIT:` / `REVERT:` lines).
+No `crash.log` + a `startup.log` that runs to `===` means it was not a panic;
+absent process with no crash.log is the signature of an external (tree) kill.
+
+## Embedded permissions — ab OWNS the prompt; Hydrogen gets a MIRROR (v1.9.191+)
+
+⚠ This SUPERSEDES the older v1.9.156 model (Hydrogen's `auto_approve` on
+`/embedded/enter` deciding, or ab forwarding each gated command to Hydrogen's
+`/permission/request` and blocking). That is GONE.
+
+- **`auto_approve` in `POST /embedded/enter` is accepted AND IGNORED.** It used
+  to let Hydrogen pre-authorize (`true`) or force-forward (`false`). Both were
+  removed: a stale policy flooded the user with prompts, and silencing a human's
+  prompt is the HUMAN's call, not an app's. An older Hydrogen that still sends the
+  field keeps working (it is parsed and logged, not rejected).
+- **ab owns approvals in every mode.** For a gated command from a REMOTE relay
+  (cloud-AI) caller, ab shows its OWN approval UI: the in-window `#shell-approval`
+  dialog + the branded toast, and if ab's window is hidden it SHOWS the window
+  unfocused (no foreground steal) so the taskbar flashes and the user cannot miss
+  it. There is no policy for Hydrogen to set.
+- **ab MIRRORS each permission request to Hydrogen** (`mirror_permission_request`
+  → Hydrogen's control API) so Hydrogen CAN render the prompt in its own UI. The
+  mirror is NON-BLOCKING (ab no longer blocks up to 180s on Hydrogen). Hydrogen
+  posts the human's decision back to ab's **`POST /permission/resolve`** (identical
+  effect to a click inside ab), and reads current pending requests via
+  **`GET /permission/state`**. A dismiss is mirrored too, and `/permission/state`
+  self-heals a lost dismiss.
+- **ALL FOUR consent surfaces mirror, not just the shell gate (v2.1.18, wiki
+  #137).** Web-control consent (`type:"web-consent"`, carries the page origin and
+  is marked `initiatedBy:"web-page-ui"` — a page the human is on asked, not an AI
+  thread), credential import (`type:"credential-import"`), and the desktop
+  input / UIA / clipboard refusals (`type:"input-approval"`, the generic id-less
+  grant prompt) all mirror to Hydrogen alongside the shell gate — so a user who
+  blocks Windows toasts still sees every prompt in Hydrogen.
+  `POST /permission/resolve` routes a web or credential id to the right gate; the
+  decision stays in ab in every case.
+- **Silencing = a HUMAN clicks "Bypass Permissions" in ab** (human-only grant).
+  Neither Hydrogen nor the cloud-AI can flip it on programmatically.
+
+Coverage runs through one chokepoint (`consult_embedded_gate`): `shell_execute`,
+`run_script`, the WSL write/exec verbs, and the Tier-2 class (launch_process,
+write_file, delete_file, registry_set/delete, process_kill). Gated verbs accept a
+`reason` arg shown verbatim ("The AI says:") on ab's dialog + Hydrogen's mirrored
+prompt + the toast. **Only remote relay callers are gated; local callers (CLI,
+Hydrogen driving ab over the loopback direct API, bridges) are trusted by
+transport and never prompt** — so Hydrogen's own setup commands over the direct
+API run ungated with no bypass mode needed.
+
+**Discoverability:** `status.permissions.shell.embeddedPolicy` reports the mode.
+If a gated call seems to hang while embedded, a human is looking at ab's (and the
+mirrored Hydrogen) prompt — poll `/permission/state` rather than re-issue.
+
+## Inspecting state — hd_status's three orthogonal signals
+
+Hydrogen is killed and respawned many times a day (builds, upgrades), often onto a
+different control port. `hd_status` therefore never collapses its view into one
+boolean; it reports THREE independent signals:
+
+- `processPresent` — tasklist, sampled with retry to ride the ~1s kill→respawn
+  gap.
+- `controlApiReachable` — TCP to Hydrogen's control port, discovered fresh per call
+  (ports.json, never cached or hardcoded).
+- `embedded` — ab's own state (its `AppState` / embedded marker).
+
+`running = processPresent || controlApiReachable`. A mismatch between the three
+is normal mid-churn; do not treat a single snapshot as Hydrogen being dead (ab itself
+requires 3 consecutive misses over ~30s before leaving embedded mode).
+
+## The hd_* verb family
+
+ab exposes `hd_*` verbs for driving and observing Hydrogen itself (e.g. `hd_status`,
+`hd_ship`, `hd_stop`/`hd_restart`, `hd_send_files`). Architectural rule: ab
+owns host/process/repo facts (process present, exe mtime, git SHAs); anything
+about Hydrogen's OWN runtime state is fetched from Hydrogen's control API endpoints
+(`GET /health`, `GET /buildinfo`, `GET /workspace/health`) and relayed
+verbatim. Updates while embedded follow the same split: ab checks, downloads,
+SHA-verifies and STAGES its own update (`GET /update/status` shows
+`update_ready:true` when staged); Hydrogen owns the apply timing and triggers
+`POST /update/apply`. Embedded ab never auto-applies.
+
+## The Hydrogen-managed relay entry is READ-ONLY
+
+The server entry Hydrogen injects at spawn is tagged `added_by == "hd-spawn"` and is
+ephemeral (stripped on config persist, re-added each Hydrogen launch). While
+embedded it cannot be disconnected, edited, or removed — the backend refuses
+(`is_hd_managed` guard + `HD_MANAGED_REFUSAL`) on `disconnect_server`,
+`remove_server`, `update_server`, the upsert branch of `add_server`, and the
+relay `server_add`/`server_remove` handlers, because any of those would break
+the embedded session. The UI shows it as a "Managed by Hydrogen" row with a locked
+note instead of editable fields. Do not try to work around the refusal; the
+entry is torn down automatically when ab reverts to standalone.

@@ -0,0 +1,453 @@+---
+name: adom-bridge-installer
+description: How to invoke the Adom Bridge NSIS installer from a parent installer (especially Hydrogen's setup steps) — silent install, /NOLAUNCH switch for Hydrogen-managed bundling, live progress via the structured log file at %TEMP%\adom-bridge-install.log. Use when bundling ab inside another Windows installer, writing an install supervisor / setup-step UI, detecting ab's installed version, or upgrading an existing ab install programmatically.
+---
+
+# Adom Bridge installer integration
+
+Adom Bridge (ab) ships as a single NSIS installer:
+
+```
+Adom Bridge_<version>_x64-setup.exe   (~4.8 MB on v1.8.45)
+```
+
+It installs to `%LOCALAPPDATA%\Adom Bridge\` — no UAC prompt, no admin needed. Tauri-2 bundled NSIS with our customisations in `src-tauri/installer-hooks.nsh`.
+
+## Command-line surface
+
+| Flag | Meaning |
+|---|---|
+| (none) | Installs silently, auto-launches `adom-bridge.exe` after install |
+| `/S` | Standard NSIS silent flag — same behavior since the top-level `SilentInstall silent` directive already suppresses UI |
+| `/NOLAUNCH` | **v1.8.45+** — install silently, do NOT auto-launch after install. Caller is responsible for spawning ab with the desired flags |
+| `/NODESKTOP` | **v2.0.95+** — do NOT create the desktop shortcut ("Bridge" on `$DESKTOP`). Also REMOVES a desktop icon left by an earlier default install, so passing it on every upgrade converges the box to no-desktop-icon. Start Menu shortcut + AUMID registration (toasts, taskbar tile) are untouched. Recommended for Hydrogen-managed bundling: the user launches ab through Hydrogen, so a second desktop icon next to "Adom Hydrogen" is clutter |
+| `/D=<path>` | Install destination override. Default is `$LOCALAPPDATA\Adom Bridge`. Rarely needed |
+| `<uninstall.exe> /S` | Silent uninstall. The uninstaller lives at `%LOCALAPPDATA%\Adom Bridge\uninstall.exe` |
+
+**UI behavior**: zero UI in all cases. `SilentInstall silent` is set at the top of the NSIS script, so even `setup.exe` invoked from Explorer runs without a window. No Welcome page, no progress bar, no Finish page.
+
+**Auto-launch**: by default the installer calls `ExecShell "" "$INSTDIR\adom-bridge.exe"` at the end of POSTINSTALL. Pass `/NOLAUNCH` to suppress this. Used by Hydrogen when bundling ab because Hydrogen wants to spawn ab with `--embedded --start-hidden --relay-url ... --session-token ...` itself, not let ab launch standalone first and get respawned via single-instance.
+
+## Live progress log
+
+The installer writes structured progress to `%TEMP%\adom-bridge-install.log` (Windows expands `%TEMP%` to the user's temp dir, typically `C:\Users\<name>\AppData\Local\Temp`). Each line is `[STAGE] message\r\n`:
+
+```
+[START] adom-bridge installer 1.8.45 starting
+[PREINSTALL] Cleaning legacy desktop shortcuts
+[PREINSTALL] Done. Tauri will now copy bundle files.
+[POSTINSTALL] Bundle files copied. Cleaning Tauri's auto-created desktop shortcut.
+[POSTINSTALL] /NOLAUNCH passed — skipping auto-launch (caller will spawn)
+[DONE] adom-bridge installer complete (no-launch mode)
+```
+
+**`[START]`** opens with a truncated write (fresh log per install). **`[DONE]`** is always the final line — readers tailing the file can use that as the completion sentinel without needing to wait for the process exit.
+
+Stage tags currently emitted:
+- `[START]` — once, at the top
+- `[PREINSTALL]` — Tauri's beforeBuildCommand hook ran, files about to be copied
+- `[POSTINSTALL]` — files copied; Tauri's standard shortcuts created and our hook is cleaning the unwanted ones
+- `[DONE]` — final line, installer about to exit
+
+The uninstaller writes the same log with `[PREUNINSTALL]` / `[POSTUNINSTALL]` stages.
+
+## Recipe: Hydrogen's setup-step UI tails the log
+
+Spawn the installer with `/NOLAUNCH`, poll the log file on a 200 ms timer, surface each new line to Hydrogen's UI. When `[DONE]` shows up OR the process exits, the install is complete.
+
+### Rust (Hydrogen's installer driver)
+
+```rust
+use std::{env, fs, path::PathBuf, process::Command, time::Duration};
+use std::os::windows::process::CommandExt;
+use tokio::time::sleep;
+
+const CREATE_NO_WINDOW: u32 = 0x08000000;
+
+async fn install_adom_bridge<F: FnMut(String)>(
+    installer_path: &str,
+    mut on_line: F,
+) -> Result<(), String> {
+    let log_path: PathBuf = [&env::var("TEMP").map_err(|e| e.to_string())?, "adom-bridge-install.log"]
+        .iter()
+        .collect();
+    // Pre-clear so we don't read stale lines from a previous install.
+    let _ = fs::remove_file(&log_path);
+
+    let mut child = Command::new(installer_path)
+        .args(["/S", "/NOLAUNCH"])
+        .creation_flags(CREATE_NO_WINDOW)
+        .spawn()
+        .map_err(|e| format!("spawn installer: {e}"))?;
+
+    let mut last_pos = 0usize;
+    loop {
+        // Tail any new content
+        if let Ok(content) = fs::read_to_string(&log_path) {
+            if content.len() > last_pos {
+                let slice = &content[last_pos..];
+                if let Some(last_nl) = slice.rfind('\n') {
+                    let consumed = &slice[..=last_nl];
+                    for line in consumed.lines() {
+                        on_line(line.to_string());
+                        if line.starts_with("[DONE]") {
+                            // Don't return yet — wait for process exit
+                            // so we surface the actual exit code, but
+                            // we know progress streaming is finished.
+                        }
+                    }
+                    last_pos += consumed.len();
+                }
+            }
+        }
+        // Check if installer has exited
+        if let Some(status) = child.try_wait().map_err(|e| e.to_string())? {
+            return if status.success() {
+                Ok(())
+            } else {
+                Err(format!("installer exited with {}", status))
+            };
+        }
+        sleep(Duration::from_millis(200)).await;
+    }
+}
+
+// Caller:
+// install_adom_bridge(r"C:\path\to\Adom Bridge_1.8.45_x64-setup.exe", |line| {
+//     hd_setup_step.append_live_output(&line);
+// }).await?;
+```
+
+### Bash (debugging / scripting)
+
+```bash
+# Pre-clear stale log
+rm -f "$TEMP/adom-bridge-install.log" 2>/dev/null
+
+# Spawn installer in background, tail the log
+"./Adom Bridge_1.8.45_x64-setup.exe" /S /NOLAUNCH &
+INSTALLER_PID=$!
+
+# Tail until process exits OR [DONE] appears
+while kill -0 $INSTALLER_PID 2>/dev/null; do
+  [ -f "$TEMP/adom-bridge-install.log" ] && tail -F "$TEMP/adom-bridge-install.log" &
+  sleep 0.2
+done
+wait
+echo "Installer exited"
+```
+
+## Recipe: detect if ab is already installed (and at what version)
+
+The signed NSIS installer (`installMode: "currentUser"`) writes ab's uninstall info to `HKCU` — no admin needed. **⚠ The key name is the product name `Adom Bridge` (WITH a space), NOT `AdomBridge`** (verified live 2026-07-03). Two history notes so you don't chase the wrong key:
+- The NSIS uninstall key = the product name → `…\Uninstall\Adom Bridge` (space).
+- ab's OWN launch-time code used to ALSO write an `AdomBridge` (no-space) key to **HKLM** — that write was **DELETED in v1.9.68** (the no-UAC fix). So `AdomBridge` no longer exists anywhere; read `Adom Bridge`.
+
+```
+HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\Adom Bridge
+  DisplayName       = "Adom Bridge"
+  DisplayVersion    = "1.9.74"
+  InstallLocation   = "C:\Users\<name>\AppData\Local\Adom Bridge"
+  UninstallString   = "C:\Users\<name>\AppData\Local\Adom Bridge\uninstall.exe"
+  Publisher         = "Adom Industries, Inc."
+```
+
+```rust
+use winreg::enums::HKEY_CURRENT_USER;
+use winreg::RegKey;
+
+fn adom_bridge_installed_version() -> Option<String> {
+    let hkcu = RegKey::predef(HKEY_CURRENT_USER);
+    // NOTE the SPACE — the NSIS uninstall key is the product name "Adom Bridge".
+    let key = hkcu
+        .open_subkey(r"Software\Microsoft\Windows\CurrentVersion\Uninstall\Adom Bridge")
+        .ok()?;
+    key.get_value("DisplayVersion").ok()
+}
+```
+
+Compare with `semver::Version::parse` to decide whether to skip / upgrade / leave-alone.
+
+## Recipe: Hydrogen's setup-step ladder for embedding ab
+
+The full pattern Hydrogen's setup-step UI runs when embedding ab:
+
+```
+1. Check installed version          → registry read above
+2. Decide:
+     no install         → install bundled ab
+     older than bundled → install bundled ab (upgrade)
+     same or newer      → skip install entirely
+3. Run installer (silent + /NOLAUNCH)   → tail log, surface to UI
+4. Write embedded marker file       → %LOCALAPPDATA%\Adom Bridge\embedded.json
+5. Delete ab's user-facing shortcuts → Start Menu, Desktop, Startup folder
+                                       (so user can't double-launch standalone)
+6. Spawn ab with embedded flags     → adom-bridge.exe --embedded
+                                          --start-hidden
+                                          --relay-url ws://127.0.0.1:8765
+                                          --relay-name hydrogen-desktop
+                                          --session-token <hd's token>
+7. Poll ab's direct API for liveness → GET http://127.0.0.1:47200/health
+```
+
+Steps 4 and 5 are also covered by ab's installer if you pass `--embedded` at ab's first launch (the embedded-mode detection writes the marker and ab's autostart-upgrade routine handles its own shortcuts). Doing them in Hydrogen's installer is belt-and-suspenders.
+
+## Bundle-resource pattern
+
+Hydrogen's `tauri.conf.json` should include the ab installer as a bundle resource so it ships inside Hydrogen's NSIS installer:
+
+```json
+"bundle": {
+  "resources": {
+    "resources/Adom Bridge_1.8.45_x64-setup.exe": "resources/"
+  }
+}
+```
+
+At runtime Hydrogen finds it under its install dir at `$INSTDIR\resources\Adom Bridge_<ver>_x64-setup.exe` — pass that path to the install function above.
+
+## Versioning + upgrade strategy
+
+| Scenario | What Hydrogen's installer should do |
+|---|---|
+| No ab installed | Install bundled version |
+| ab older than bundled | Install bundled version (upgrade) |
+| ab same as bundled | Skip install step; still spawn with embedded flags |
+| ab newer than bundled | Skip install step; spawn with embedded flags. Don't downgrade — embedded mode works for any ab ≥ v1.8.42 |
+
+The bundled ab installer is the minimum supported version for the Hydrogen release. Hydrogen can spawn newer ABs without modification.
+
+## Exit codes
+
+NSIS returns:
+- `0` — install succeeded
+- `2` — user cancelled (won't happen with `SilentInstall silent` since there's no UI to cancel)
+- Other — install error (rare with our hooks; typical cause is disk full or `%LOCALAPPDATA%` not writable)
+
+Treat anything non-zero as a hard failure and surface the log file's last 20 lines to the user.
+
+## Where the installer lives
+
+**v1.8.115+** — the end-user binary home is the **V2 wiki blob store** (the
+GitHub repo is private; GH release URLs 404 for anonymous downloads). Two
+discovery surfaces, both anonymous:
+
+**Preferred for parent installers (Hydrogen setup): the packages API.** Resolve
+the latest registered version and its assets in one or two GETs — note
+`?org=adom` is REQUIRED (the slug exists in multiple orgs; bare URLs 400):
+
+```
+https://wiki.adom.inc/api/v1/packages/adom-bridge/dist-tags?org=adom
+  → {"dist_tags":{"latest":"X.Y.Z"}}
+https://wiki.adom.inc/api/v1/packages/adom-bridge/manifest?org=adom
+  → { version, ..., assets: { "windows-x64": { filename, url, sha256, size } } }
+```
+
+The `assets` map is server-derived from the page's blobs (sha256 computed
+from the actual bytes — integrity-checkable). `assets[...].url` is
+server-relative (`/blob/app/adom-bridge/<file>`); prefix the git-wiki host.
+
+**Fallback / updater path: version.json**, V2-first with V1 fallback:
+
+```
+https://wiki.adom.inc/api/v1/pages/adom-bridge/files/version.json
+https://wiki.adom.inc/api/v1/pages/adom-bridge/files/version.json
+```
+
+The V2 manifest's `windows.installer_url` / `cli.<plat>.binary_url` point at
+the V2 files endpoint; V1's point at V1 static copies. **Follow the
+manifest's URLs — do NOT construct binary URLs by hand.**
+
+Network quirk: HEAD on V2 blob/file URLs may return 404 while GET works
+(git-wiki #40 — fix in flight). Probe with a Range GET (`Range: bytes=0-0`,
+expect 206), never bare HEAD. Asset filenames are dot-form everywhere
+(`Adom.Bridge_<ver>_windows_x64-setup.exe`); V1 dot-normalized since v1.8.72.
+
+The wiki page's `metadata.install.windows_installer` field points at the
+canonical filename for the current published version. Hydrogen's release build
+should fetch the latest via the V2-first pattern:
+
+```bash
+# Try V2 first, fall back to V1.
+fetch_manifest() {
+  curl -fL --max-time 15 \
+    "https://wiki.adom.inc/api/v1/pages/adom-bridge/files/version.json" \
+    2>/dev/null \
+  || curl -fL --max-time 15 \
+    "https://wiki.adom.inc/api/v1/pages/adom-bridge/files/version.json"
+}
+
+MANIFEST=$(fetch_manifest)
+INSTALLER_URL=$(echo "$MANIFEST" | jq -r .windows.installer_url)
+INSTALLER_SHA=$(echo "$MANIFEST" | jq -r .windows.installer_sha256)
+# Each manifest carries a self-consistent installer_url that points at the
+# SAME backend the manifest was served from — V2 manifest → V2 installer URL,
+# V1 manifest → V1 installer URL. No URL mixing across backends.
+
+curl -fL "$INSTALLER_URL" -o resources/ad-setup.exe
+
+# Verify SHA256 before bundling — defends against partial fetches + tampering
+DOWNLOAD_SHA=$(sha256sum resources/ad-setup.exe | awk '{print $1}')
+[ "$DOWNLOAD_SHA" = "$INSTALLER_SHA" ] || { echo "SHA mismatch"; exit 1; }
+```
+
+The desktop ab's built-in auto-updater (`src-tauri/src/updater.rs`) walks an
+ordered `MANIFEST_URLS` list — V2 first, V1 fallback — and uses whichever
+responds first. Once V2 has been the source of truth for a release cycle
+without incident, V1 will be retired from the pipeline.
+
+`version.json` also carries the SHA256 hash of the installer so Hydrogen's build
+pipeline can verify the download before bundling.
+
+## Asset naming convention (v1.8.113+)
+
+The Adom Bridge wiki page hosts TWO distinct types of artifacts per release:
+
+1. **Full ab GUI installer** — the actual desktop app (Tauri window, bundled
+   bridges, relauncher). One per OS / architecture.
+2. **CLI companion binary** — a separate executable that talks to ab over
+   the relay. Used by Hydrogen's WSL2 container, gallia builds, sibling-app
+   installers, cron jobs. Does NOT contain ab itself.
+
+Both ship together at the same version (single `python scripts/bump-version.py
+patch` bumps both, single `cargo tauri build` + `cargo build --release` in
+`cli/` produces both, single `scripts/release-publish.sh` uploads both).
+
+### Filename pattern
+
+| Artifact | Wiki asset name pattern | Example (v1.8.113) |
+|---|---|---|
+| Full ab GUI — Windows | `Adom.Bridge_<ver>_windows_x64-setup.exe` | `Adom.Bridge_1.8.113_windows_x64-setup.exe` |
+| Full ab GUI — macOS | `Adom.Bridge_<ver>_macos_<arch>.dmg` | `Adom.Bridge_1.8.113_macos_aarch64.dmg` (future) |
+| Full ab GUI — Linux | `Adom.Bridge_<ver>_linux_<arch>.AppImage` | `Adom.Bridge_1.8.113_linux_x86_64.AppImage` (future) |
+| CLI companion — Linux | `adom-bridge_<ver>_linux_<arch>` | `adom-bridge_1.8.113_linux_x86_64` |
+| CLI companion — macOS | `adom-bridge_<ver>_macos_<arch>` | `adom-bridge_1.8.113_macos_aarch64` (future) |
+| CLI companion — Windows | `adom-bridge_<ver>_windows_<arch>.exe` | `adom-bridge_1.8.113_windows_x64.exe` (future) |
+
+The `_cli_` token in the middle is the only signal you need to know "this is
+the companion, not the app." `linux_x86_64` always means Linux x86_64,
+regardless of whether the file is a GUI installer or a CLI binary.
+
+### After install, the binary name is `adom-bridge`
+
+The wiki asset name disambiguates at FETCH time. At INSTALL time the binary
+is renamed to `adom-bridge` so the command users type doesn't change:
+
+```bash
+# Linux example — install the CLI companion
+curl -fL "https://wiki.adom.inc/api/v1/pages/adom-bridge/files/adom-bridge_1.8.113_linux_x86_64" \
+  -o /tmp/ad
+sudo install -m 755 /tmp/ad /usr/local/bin/adom-bridge
+adom-bridge --version
+# → adom-bridge 1.8.113 (<sha>, built <ts>)
+```
+
+### Version.json `.cli` slot
+
+The auto-update manifest (v1.8.113+) carries a typed `cli` sibling section
+for the CLI binaries:
+
+```json
+{
+  "manifest_version": 1,
+  "version": "1.8.113",
+  "windows": { "installer_url": ".../Adom.Bridge_1.8.113_windows_x64-setup.exe", ... },
+  "cli": {
+    "linux_x86_64": {
+      "binary_url":      ".../adom-bridge_1.8.113_linux_x86_64",
+      "binary_filename": "adom-bridge_1.8.113_linux_x86_64",
+      "binary_sha256":   "...",
+      "binary_size":     8012408
+    }
+  },
+  "changelog_url": "...",
+  "minimum_required": "1.3.30"
+}
+```
+
+Pre-v1.8.113 readers ignore `.cli` entirely (additive schema; no
+`manifest_version` bump required). The desktop ab's own auto-updater only
+reads `.windows / .macos / .linux` for its GUI installer URL — it doesn't
+touch `.cli`.
+
+For Hydrogen / gallia / Docker-side fetchers, prefer the typed lookup:
+
+```bash
+# Best: read the URL out of the manifest (so the filename can evolve)
+MANIFEST=$(fetch_manifest)
+LINUX_CLI_URL=$(echo "$MANIFEST" | jq -r '.cli.linux_x86_64.binary_url')
+LINUX_CLI_SHA=$(echo "$MANIFEST" | jq -r '.cli.linux_x86_64.binary_sha256')
+curl -fL "$LINUX_CLI_URL" -o /tmp/ad
+[ "$(sha256sum /tmp/ad | awk '{print $1}')" = "$LINUX_CLI_SHA" ] || exit 1
+sudo install -m 755 /tmp/ad /usr/local/bin/adom-bridge
+```
+
+### Windows CLI is shipped with the NSIS (v1.8.114+)
+
+Installing ab on Windows now drops the CLI companion next to the GUI exe
+and adds the install dir to the user's PATH so PowerShell / Claude Desktop /
+cmd find it without configuration:
+
+```
+%LOCALAPPDATA%\Adom Bridge\adom-bridge.exe        ← GUI (Windows subsystem)
+%LOCALAPPDATA%\Adom Bridge\adom-bridge-cli.exe    ← CLI companion (Console subsystem)
+%LOCALAPPDATA%\Adom Bridge\ad-relauncher.exe       ← visible self-restart helper
+```
+
+NSIS's POSTINSTALL hook prepends `%LOCALAPPDATA%\Adom Bridge` to
+`HKCU\Environment\Path` (no UAC — user-level only) and broadcasts
+`WM_SETTINGCHANGE` so freshly-opened shells pick up the change. Already-
+open shells need a re-launch (OS limitation).
+
+After install, in a fresh PowerShell:
+
+```powershell
+adom-bridge --version
+# adom-bridge 1.8.114 (<sha>, built <ts>)
+adom-bridge status
+adom-bridge screenshot_window '{"title-contains":"VS Code"}'
+```
+
+The CLI auto-discovers the local ab via direct-API probe at
+`127.0.0.1:47200` — no relay needed when ab is on the same box. ~5ms RTT
+for compatible verbs; verbs in ab's `cliRequired` list still flow through
+a relay if one's running (Hydrogen's WSL2 distro typically owns the relay).
+
+**Relay self-detect (v1.8.114+):** `adom-bridge serve` checks for
+another adom-bridge relay on `127.0.0.1:8766/health` before binding. If
+one already answers, it prints a friendly note and exits cleanly without
+starting a second relay (which would just sit idle — ab's WS client only
+attaches to the first one it finds). Pass `--force-bind` to override.
+
+PREUNINSTALL strips the PATH entry back out and rebroadcasts so an
+uninstall of ab also gets PATH cleanup.
+
+### Legacy alias migration window
+
+Releases prior to v1.8.113 published the Linux CLI as `adom-bridge-linux`
+(no version, no architecture). Hydrogen's WSL2 setup and a few cron-based
+installers have that literal filename baked in.
+
+To keep them working through the rename, v1.8.113 publishes BOTH names:
+
+| Name | Status | Wiki URL (V2 / V1) |
+|---|---|---|
+| `adom-bridge_<ver>_linux_x86_64` | **canonical, v1.8.113+** | V2 / V1 |
+| `adom-bridge-linux` | **deprecated alias** — byte-identical copy | V2 / V1 |
+
+Both files are byte-identical with the same SHA256. The legacy alias stays
+through **v1.8.116**, then disappears. Migrate by then. Recommended pattern:
+
+```bash
+# Migration period (v1.8.113 → v1.8.115): try new name, fall back to alias
+LINUX_CLI_URL_NEW=$(echo "$MANIFEST" | jq -r '.cli.linux_x86_64.binary_url // empty')
+if [ -n "$LINUX_CLI_URL_NEW" ]; then
+  curl -fL "$LINUX_CLI_URL_NEW" -o /tmp/ad
+else
+  # Falling back — likely talking to a pre-v1.8.113 manifest
+  curl -fL "https://wiki.adom.inc/api/v1/pages/adom-bridge/files/adom-bridge-linux" \
+    -o /tmp/ad
+fi
+```
+
+Post-v1.8.116, the fallback branch dies; only the canonical name will exist.

@@ -0,0 +1,123 @@+---
+name: adom-bridge-local-ai
+description: Drive this Windows PC from a LOCAL AI tool (Claude Desktop, Claude Code, Codex, or any agent running on the same machine) through Adom Bridge's bundled CLI, adom-bridge-cli.exe. No relay, no cloud container, no --target. Use when the user says "Claude Desktop, control my PC", "use adom-bridge from Claude Code on Windows", "local AI, drive my desktop", or when you find adom-bridge-cli.exe on PATH. Covers the bundled CLI, the auto-linked consumer skills, loopback direct-API routing, and a starter verb cookbook.
+---
+
+# Adom Bridge from a local AI (same-PC, no relay)
+
+Adom Bridge (ab) is the automation surface for this Windows machine. If ab is
+installed here, any AI tool running on the SAME PC (Claude Desktop, Claude
+Code, Codex, a local script or agent) can drive the desktop through the
+bundled CLI. The cloud-container path over the WebSocket relay is a different
+setup and is covered elsewhere (see "When you DO need the relay" below).
+
+## What the Windows installer lays down for local AIs
+
+The signed NSIS installer puts everything a local agent needs in place:
+
+- **`adom-bridge-cli.exe`** is bundled next to the GUI at
+  `%LOCALAPPDATA%\Adom Bridge\`. The installer adds that directory to the
+  user PATH (HKCU, no elevation) and broadcasts the environment change, so
+  freshly opened shells can run `adom-bridge-cli.exe` by name. Its required
+  `vcruntime140.dll` ships app-local next to it, so it launches even on a
+  machine with no VC++ Redistributable.
+- **Consumer skills are auto-linked into your agents.** The installer bundles
+  the consumer skill set at `%LOCALAPPDATA%\Adom Bridge\bundled-skills\<slug>\SKILL.md`,
+  and on EVERY launch ab copies each skill into BOTH
+  `~/.claude/skills/<slug>/` and `~/.codex/skills/<slug>/`. So a local
+  Claude Desktop / Claude Code / Codex picks up ab's docs with zero user steps.
+
+Auto-link behavior (from `src-tauri/src/skills_install.rs`):
+
+- **Idempotent and cheap.** A skill is (re)written only when the destination
+  is missing or its bytes differ from the bundled copy. A steady-state launch
+  does zero disk writes.
+- **`.adom-managed` marker.** Each directory ab creates carries a
+  `.adom-managed` marker file. ab refreshes a skill (on an ab upgrade) only
+  when the marker is present.
+- **Never clobbers your own skills.** A same-slug directory WITHOUT the
+  marker (hand-made, or installed by a package) is left untouched.
+- **Opt out:** launch ab with `ADOM_SKILLS_LINK=0` to disable the auto-link.
+- Runs in both standalone and embedded (under Hydrogen) modes, and is
+  best-effort: it can never fail or delay ab's launch.
+
+## How a local AI calls ab
+
+Run the CLI with a verb and a JSON args object, and NO `--target`:
+
+```
+adom-bridge-cli.exe <verb> '<json-args>'
+```
+
+With no target set, the CLI short-circuits to the GUI's **loopback direct
+API**: it reads `~/.adom/direct-api-port` (written by the GUI at bind time,
+contents `host:port`, e.g. `127.0.0.1:47201`), falls back to probing
+`127.0.0.1:47200` and scanning `47201..47209` if the file is missing, and
+POSTs straight into the running GUI process. No relay, no container, no
+WebSocket, no auth-token dance. Responses are the same JSON shape as every
+other path, including `_hint`, `errorCode`, and `status` fields.
+
+**Local callers are trusted by transport.** The direct API binds
+`127.0.0.1` only, so a caller on this machine already got here by being
+installed on this machine. The shell approval gate applies only to remote
+relay (cloud AI) callers; the local CLI is not gated.
+
+## Verb discovery
+
+```
+adom-bridge-cli.exe commands
+```
+
+lists every available verb with args and return shapes (aliases: `help`,
+`list_commands`). Unknown-verb responses also carry a hint pointing at the
+discovery list.
+
+## Starter cookbook
+
+```bash
+# Is ab up? (ping uses its own direct-API path)
+adom-bridge-cli.exe ping
+
+# Enumerate visible top-level windows (returns hwnds + titles)
+adom-bridge-cli.exe desktop_list_windows
+
+# Capture one window, chrome included (lossless PNG)
+adom-bridge-cli.exe desktop_screenshot_window '{"hwnd": 123456}'
+# ...or match by title:
+adom-bridge-cli.exe desktop_screenshot_window '{"titleContains": "Notepad"}'
+
+# Whole-screen capture
+adom-bridge-cli.exe desktop_screenshot_screen
+
+# Show the user a Windows toast notification
+adom-bridge-cli.exe notify_user '{"title":"Build done","body":"All tests passed"}'
+
+# Launch an app (path-verified; never triggers "Windows cannot find" dialogs)
+adom-bridge-cli.exe launch '{"name":"notepad"}'
+
+# Run a shell command through ab's structured verb
+adom-bridge-cli.exe shell_execute '{"command":"echo hello"}'
+```
+
+Prefer ab's structured verbs (`launch`, `find_exe`, `desktop_*`, `notify_user`)
+over raw shell where one exists: they validate inputs and return structured
+JSON with hints.
+
+## When you DO need the relay
+
+The direct API only reaches the ab on THIS machine. To drive a REMOTE
+machine (another PC's ab connected to the same relay), the CLI routes over
+the relay with `--target <clientName>`; a cloud container always uses the
+relay. That path, including multi-machine addressing and targeting rules, is
+documented in the main `adom-bridge` skill (`skills/SKILL.md`) and
+`skills/MULTI_AB_ADDRESSING.md`. This skill is only about the local,
+no-relay case.
+
+## Sibling apps: skip the CLI entirely
+
+A sibling app or local process can also POST JSON commands directly to ab's
+loopback HTTP API (`POST http://127.0.0.1:<port>/command` with
+`{"command": "...", "args": {...}}`, port discovered from
+`~/.adom/direct-api-port`) without spawning the CLI at all. The full
+contract, including port discovery, endpoints, and update routes, is in the
+`adom-bridge-direct-api` skill (`skills/DIRECT_API.md`).

@@ -0,0 +1,239 @@+---
+name: adom-bridge-multi-ad
+description: Address and fan out to multiple Adom Bridges on one relay. Use when more than one machine runs Adom Bridge on the same relay and you need to target a specific one (--target <name>) or broadcast to all (--target all) — e.g. a laptop plus an Azure VM. Covers client naming, --target, the targets verb, and ambiguous-target handling.
+---
+
+# Multi-ab addressing — name + fan out to many Adom Bridges on one relay
+
+> **Status: PLANNED (not yet implemented) — design + verified architecture map, captured 2026-06-14.**
+> This is the golden reference for the "one cloud relay → many named ABs" feature. The "Verified
+> current architecture" section is true of the codebase as of this date (file:line refs); the
+> "Design" section is the approved implementation plan. Re-verify the line numbers before coding —
+> they drift.
+>
+> **Trigger words:** multiple Adom Bridges, multiple ABs, two laptops, azure vm ab, last one wins,
+> last ab wins, relay fight, ab fighting, commands go to wrong machine, target a specific ab,
+> --target, ADOM_TARGET, broadcast to all ABs, fan out, talk to hundreds of ABs, name each ab,
+> client name, machine name, addressable ab, relay multi-client, appName eviction, first_client_id.
+
+---
+
+## Context (why this exists)
+
+Hydrogen (which embeds Adom Bridge) gets installed on multiple machines — a Windows
+laptop and an Azure test VM, eventually many — all pointed at **one** cloud relay (galliaApril's
+`adom-bridge serve`). They **fight**: when an ab authenticates, the relay evicts any existing
+client with the **same `appName`**, and every ab auths as `appName:"Adom Bridge"`, so the last ab
+to connect evicts the others. The cloud AI's commands then land on whichever box connected last
+(commands meant for the laptop hit the Azure VM, silently — the bug that motivated this).
+
+**Goal:** every ab stays connected and is **addressable by name** (`adomlapper`, `azurevm`), with
+the ability to **fan one command out to all** ("I kinda like the idea that my main cloud container
+could almost talk to 100s of ABs out there on different boxes" — the user).
+
+**Locked product decisions** (asked + answered 2026-06-14):
+1. **Friendly name, default = hostname.** Each ab has a configurable name, defaulting to its OS hostname.
+2. **Include `--target all` fan-out now** — one command → every ab, results aggregated per machine.
+3. **No-target + multiple ABs → ERROR and list the connected names** (never guess which box).
+
+---
+
+## Key insight — this is an extension, not a new layer
+
+The user worried this was "a whole other layer we'd have to shim in." It isn't. The infra is ~90%
+there; the "fight" is a single piece of code.
+
+- The relay already stores **all** clients in a map (not a single slot).
+- Every ab already sends its **hostname** in the auth handshake — the relay already knows who's who.
+- The relay **already** does per-client targeting for TCP tunnels via an optional `clientId` — a
+  pattern to copy for commands.
+
+The fight is the **appName-keyed eviction** + routing-by-`first_client_id()`. Fix: stop evicting
+*different machines*, add a *target selector*, add *broadcast aggregation*.
+
+---
+
+## Verified current architecture (2026-06, file:line — re-verify before coding)
+
+### Relay server (`cli/src/server/`)
+- `state.rs` — `AppState.clients: Mutex<HashMap<String, ClientInfo>>` keyed by a per-connection
+  UUID `client_id`. **Already multi-client.** `ClientInfo { id, tx: mpsc::UnboundedSender<Message>,
+  authenticated, capabilities, app_name, user_agent, os, hostname, ip, connected_at, last_pong,
+  is_alive }`.
+- `state.rs:~204` `first_client_id()` → first authenticated client in iteration order. **The only
+  command-routing selector today.**
+- `state.rs:~188` `send_to_client(client_id, msg)`. `state.rs:~213` `send_and_wait(message,
+  timeout_ms)` → `first_client_id()` → register `pending_requests: HashMap<String, oneshot>` keyed
+  by message `id` → `send_to_client`. Response correlation is by message `id` (`resolve_pending`).
+- `state.rs:~165` `get_authenticated_clients()` → JSON rows `{id, appName, userAgent, os, hostname,
+  ip, capabilities, connectedAt, lastPong}`.
+- `ws.rs:~598-691` auth handshake reads `{token, appName, userAgent, os, hostname, capabilities}`.
+  **`ws.rs:~614-632` THE EVICTION:** on auth, removes all OTHER authenticated clients whose
+  `app_name == this app_name`. (Exists to clean up a same-machine ab reconnect/zombie — but
+  over-matches across machines.)
+- `mod.rs` HTTP API (port discovered, default 8766): `mod.rs:~315` `get_clients` action;
+  `mod.rs:~424-564` tunnel actions with an **optional `clientId` selector** (`mod.rs:~446`:
+  `if let Some(cid)=body.get("clientId")… else first_client_id()`) — **copy this for commands**;
+  `mod.rs:~350` a **fire-and-forget `broadcast`** action (no await/aggregate — **do NOT reuse**;
+  add a distinct `send_and_wait_multi`). Relay ports discovery file: `~/.adom/cli-relay-ports.json`.
+
+### ab GUI (`src-tauri/`)
+- `protocol.rs:~99-112` `WsMessage::auth(token, hostname)` → payload `{token, appName:"Adom
+  Desktop", userAgent, os, hostname, capabilities}`. Envelope: `WsMessage { msg_type, id, payload }`.
+  **Does NOT currently send `version` or any self-name beyond hostname.**
+- `ws_client.rs` — `spawn_ws_loop` / `run_supervisor` (30s) / `run_ws_loop` /
+  `connect_and_run(app: &AppHandle, …)` (15s connect timeout ~L292). `~L316-321` derives
+  `hostname::get()` and sends auth. `app` is in scope → config + embedded state reachable.
+- `state.rs:~46-69` `ServerEntry { id, name, url, auth_token, auto_connect, enabled, added_by }`;
+  `AppConfig { servers, kicad_library_paths, file_receive_directory, project_watch, update_mode,
+  shell_auto_approve_permanent, always_show_window_on_launch }` at `~/.adom/config.json`.
+  load/save in `lib.rs` (~52/65/191).
+- `embedded.rs` `parse_cli_flags()` parses `--embedded`, `--relay-url`, `--relay-name`,
+  `--start-hidden`, `--shell-approval`. **`--relay-name` is taken** (= the relay's display name in
+  ab's server list, NOT this ab's self-name) — so the self-name flag must be **`--client-name`**.
+- `hostname` crate is already a dep (0.4).
+
+### CLI caller (`cli/src/`)
+- `relay.rs:~7` `api_url()` = env `ADOM_API` or `http://127.0.0.1:8766`. `relay.rs:~87-113`
+  `desktop_command(app, command, args, timeout_ms)` → tries a **direct-API short-circuit**
+  (`direct_probe::should_use_direct(command)` → `direct_call` to the LOCAL GUI at
+  **`127.0.0.1:47200`**) else falls back to `send_and_wait`. `relay.rs:~46` `send_and_wait` POSTs
+  `{message, timeoutMs}` to the relay `send_and_wait` action. `relay.rs:~40` `get_clients()`.
+- `commands.rs:~44-554` `run_inner(command, args)` giant match; **all verbs funnel through
+  `relay::desktop_command(...)`**. `status` (~L1629) already calls `get_clients`.
+- `main.rs:~40-94` clap `Cli` with `Commands::Command(Vec<String>)` via
+  `#[command(external_subcommand)]` (**swallows all verb args raw — clap never sees flags**). Env
+  vars honored: `ADOM_API`, `ADOM_WS_PORT`, `ADOM_HTTP_PORT`, `ADOM_AUTH_TOKEN`. **No global flags.**
+- `direct_probe.rs` probes `127.0.0.1:47200` (+ `host.docker.internal:47200` for Hydrogen's local Docker).
+
+---
+
+## Design
+
+### Protocol additions (shared contract)
+- **Auth payload (ab → relay):** add `clientName` (resolved friendly name) + `version`
+  (`env!("CARGO_PKG_VERSION")`) to `WsMessage::auth`; keep `hostname`/`appName`. Optional `embedded` bool.
+- **Command request (CLI → relay `send_and_wait`):** add optional `target` (a name).
+- **New HTTP action `send_and_wait_multi`** for the awaiting/aggregating broadcast.
+
+### Component 1 — ab GUI (`src-tauri/`)
+- **Config:** `AppConfig` += `#[serde(default)] pub client_name: Option<String>` (+ `Default`).
+- **Launch flag:** `embedded.rs parse_cli_flags` += `--client-name <name>` (mirror `--relay-name`
+  arms); thread to `EmbeddedState.pending_client_name`. Lets Hydrogen set the name on the Azure VM.
+- **Persist:** `lib.rs` (~L2449) — if `pending_client_name` set, write `config.client_name` + save.
+- **Auth payload:** `protocol.rs` `WsMessage::auth(token, hostname, client_name)` → add
+  `clientName` + `version`.
+- **Resolve + send:** `ws_client.rs connect_and_run` (~L317) — `resolve_client_name(app, hostname)`
+  precedence **flag → config → hostname** (trim; fall through on empty). Read the `RwLock` in a
+  tight non-async scope (drop guard before `.await`).
+- **Settings field:** `src/main.js` + a `set_client_name` Tauri command — text input "This
+  machine's name (for cloud addressing)", default hostname, writes config + reconnects. Lets the
+  standalone laptop be named without launch-flag gymnastics; place by `always_show_window_on_launch`.
+
+### Component 2 — Relay (`cli/src/server/`)
+- **Capture identity:** `ClientInfo` += `client_name: Option<String>`, `version: Option<String>`
+  (+ optional `embedded`); read `payload["clientName"]`/`["version"]` in `handle_auth` (~L609).
+- **Stable-identity eviction** (`ws.rs:~614`): replace appName-keyed eviction with
+  `stable_identity(c) = client_name(non-empty) else hostname(non-empty) else None`. Evict only
+  OTHER authed clients whose identity matches (case-insensitive); never evict when `None`.
+  **Collision rule:** evict on `client_name` match **always**; evict on `hostname` match **only when
+  neither side has a `client_name`** — so distinct-named machines sharing a hostname coexist, and a
+  genuine same-machine reconnect still kills its zombie.
+- **Resolver + accessors** (`state.rs`):
+  - `resolve_target(target) -> One(client_id) | NotFound{requested, available}` (match `target`
+    case-insensitively against `client_name` then `hostname`).
+  - `authenticated_client_ids() -> Vec<(id, name)>` (name = client_name ?? hostname ?? id).
+  - `first_or_ambiguous() -> Single(id) | Ambiguous(Vec<name>) | None_`.
+- **Targeted send:** refactor `send_and_wait` body → `send_and_wait_to(message, timeout, client_id)`;
+  `send_and_wait` = `first_client_id()? → send_and_wait_to`. Message-`id` correlation preserved.
+- **Broadcast:** `send_and_wait_all(message, timeout)` — snapshot `authenticated_client_ids()`,
+  clone the message per target with a **fresh distinct `id`** (reusing one id cross-wires
+  responses), `join_all` the per-target `send_and_wait_to`; per-target timeout/failure →
+  `{ok:false,error,timedOut:true}` for that machine only (never fails the batch).
+- **HTTP dispatch** (`mod.rs api_handler` ~L314): `send_and_wait` reads optional `target`
+  (present&≠"all" → `resolve_target`→`send_and_wait_to` or `target_not_found`; absent →
+  `first_or_ambiguous`: Single→send, Ambiguous→`ambiguous_target`, None_→existing "No desktop
+  client connected"); add `send_and_wait_multi` → `send_and_wait_all`.
+- **List:** `get_authenticated_clients` (~L165) += `clientName`, `version` (+ `embedded`).
+
+### Component 3 — CLI caller (`cli/src/`)
+- **Strip `--target` before dispatch** (`main.rs`, `Commands::Command(args)` arm ~L197):
+  `extract_target(&mut args)` removes `--target <v>` / `--target=<v>` / `-t <v>` from the raw Vec
+  (scan whole Vec → works after the verb too). Precedence: flag > `ADOM_TARGET` env. `"all"` is a
+  passthrough sentinel.
+- **Thread it** (`relay.rs`): process-global `static TARGET: OnceLock<Option<String>>` set once in
+  `main.rs` (avoids editing ~40 call sites). `desktop_command`: if a target is set (any, incl.
+  "all") → **skip the direct-API short-circuit** (local-GUI-only). `send_and_wait`: `Some("all")` →
+  POST `send_and_wait_multi`, return aggregate verbatim; `Some(name)` → POST `send_and_wait` with
+  `target:name` (keep single unwrap); `None` → unchanged.
+- **`targets` verb** (`commands.rs`, near `status`): `"targets" | "desktop_list_targets"` → formats
+  `get_clients()` as `{name, hostname, version, os, connectedAt, embedded}` + `count` + a `_hint`.
+- **Exit codes** (`main.rs`): result `error` ∈ {`ambiguous_target`, `target_not_found`} →
+  pretty-print + `exit(1)` (mirror existing structured-error path ~L263).
+- **Help-map** (`commands.rs list_commands`): `targets` entry + a top-level `_targeting_note`
+  (sibling to `_url_hint_note`) — what Docker Claude reads via `adom-bridge status`.
+
+### Result / error shapes
+```jsonc
+// --target all
+{ "broadcast": true, "targets": ["adomlapper","azurevm"],
+  "results": { "adomlapper": {/*verb payload*/},
+               "azurevm": {"ok":false,"error":"Request timed out","timedOut":true} },
+  "summary": { "total":2, "ok":1, "failed":1 } }          // duplicate names → suffix "#<idtail>"
+
+// no target, >1 ab connected (exit 1)
+{ "error":"ambiguous_target",
+  "_hint":"Multiple Adom Bridges connected. Re-run with --target <name> (or --target all).",
+  "connected":[{"name":"adomlapper","hostname":"ADOMLAPPER","version":"1.8.x"}, ...] }
+
+// --target names an ab that isn't connected (exit 1)
+{ "error":"target_not_found", "requested":"azurevm",
+  "_hint":"No connected Adom Bridge matches 'azurevm'. Connected: adomlapper, azure-vm-01.",
+  "connected":[ /* same shape */ ] }
+```
+
+### Edge cases & back-compat
+| Case | Behavior |
+|---|---|
+| Old ab (no clientName) | Relay falls back to `hostname` for identity + addressing. |
+| Old CLI (no `--target`), 1 ab | no-target → Single → unchanged. |
+| Old CLI, >1 ab | gets `ambiguous_target` JSON (self-documenting); upgrade/pass target. |
+| New CLI, no target, local direct API up | direct short-circuit preserved (fast local hop). |
+| `--target <self>` | skips direct, goes via relay — explicit + correct. |
+| Same hostname, no clientName | collide → **must set distinct `--client-name`**; once named they coexist; `targets` shows the collision. |
+| ab reconnect (zombie) | same name/hostname → stale conn evicted (intended). |
+| Broadcast partial failure/timeout | per-target error object; batch still 200 with `summary.failed`. |
+| `--target all`, 0 ABs | `{broadcast:true,targets:[],results:{},summary:{total:0,…}}`, exit 0. |
+| Hydrogen-spawned ab on Azure VM | Hydrogen appends `--client-name azurevm` to its `--embedded …` spawn (**hydrogen-desktop repo change** — coordinate; until then the VM is addressable by hostname). |
+
+### Decisions locked
+- Eviction collision: clientName-match always; hostname-match only when neither side is named.
+- `--target all` with 0 ABs → exit 0 (empty aggregate).
+- Global `OnceLock` target (vs editing ~40 call sites).
+- Settings UI field included (laptop needs a friendly name without launch-flag gymnastics).
+- Hydrogen `--client-name` spawn flag is a coordinated hydrogen-desktop change; VM works by hostname meanwhile.
+
+---
+
+## Verification (when implemented)
+
+Two ABs against one relay (the real setup: laptop ab + Azure-VM ab → galliaApril relay):
+1. Connect laptop (`--client-name adomlapper`) + VM (`--client-name azurevm`); `adom-bridge
+   targets` → 2 rows with names + versions.
+2. `adom-bridge ping` (no target) → `ambiguous_target` + both names, exit 1.
+3. `--target adomlapper` → laptop only; `--target azurevm` → VM only.
+4. `--target all` → `{broadcast:true, results:{adomlapper, azurevm}}`.
+5. `--target nope` → `target_not_found` + list, exit 1.
+6. Kill+reconnect the VM ab → `targets` still shows exactly 2 (reconnect evicted its own stale entry).
+7. Single-ab regression: disconnect VM → no-target `ping` works; local direct path unchanged.
+8. Add T-tests to `scripts/test-via-gallia.sh` for `targets`, single-target, the broadcast aggregate
+   shape, and both error shapes traversing the relay with `_hint` intact.
+
+## Build / release (when implemented)
+- `python scripts/bump-version.py patch` touches `cli/**` AND `src-tauri/**` → **both binaries
+  rebuild** (build matrix): GUI `cargo build --release` (FAST) → relauncher; relay/CLI on gallia via
+  `ssh adom-gallia … cargo build --release && sudo install …`. FULL `cargo tauri build` only for the
+  signed ship.
+- Docs in the same ship: `skills/SKILL.md` ("Addressing multiple desktops"), `README.md`, CLI
+  help-map, `CLAUDE.md` (`--client-name` + multi-ab rule), and the release-ladder Docker Claude
+  prompt (`--target` usage; drop "last ab wins"; use `targets` for discovery).

@@ -0,0 +1,269 @@+---
+name: adom-bridge-notify
+description: Send native Windows toast notifications from a cloud AI or a bridge via adom-bridge's notify_user verb, and GET THE USER'S ANSWER BACK. Two separate axes: (1) get the reply to you — wait:true blocks and returns their choice, or poll notify_events/notify_response (there is no server-push to a turn-based AI). (2) reveal a window on their screen with `focus` — a local desktop action, incl. focus:{host:true} to reveal Hydrogen when ab is embedded, and focus:{app} for any app. Use to alert the user (build done, export ready), point them at a window that needs them, show a progress bar, or ask for a decision and read it back. Covers every toast type, the exact verb calls, how the AI polls/waits for responses, and what a click actually does.
+---
+
+# Notifications — `notify_user` (native branded Windows toasts)
+
+`notify_user` fires a **real native Windows toast** under Adom Bridge's own identity (AUMID `inc.adom.bridge`, the Adom logo as the icon) — it lands in the bottom-right banner AND in Action Center history like any first-class app. It is **not** signing-dependent and **not** a PowerShell-identity hack.
+
+Reachable three ways, all identical shape:
+- **CLI / cloud:** `adom-bridge notify_user '{"title":"...","body":"..."}'`
+- **Direct API (sibling app):** `POST /command {"app":"desktop","command":"notify_user","args":{...}}`
+- **From a bridge:** the same `notify_user` verb via the relay.
+
+Returns `{ "status":"ok", "action":"displayed", "id":"...", "clickBehavior":"...", "_hint":"...", "_next":[...] }` — plus `_couldHaveDoneBetter` + `_capabilities` when the call left something on the table. **Read those.** They are how you learn what this verb can do without reading this file.
+
+## ⭐ TWO axes — do not confuse them
+
+A toast can do two *separate* things. Almost all confusion comes from mixing them up:
+
+| Axis | Field(s) | What it does | Reply to you? |
+|---|---|---|---|
+| **1 — GET THE USER'S ANSWER BACK** | `wait:true` (block-and-return), or poll `notify_events` / `notify_response` | delivers the user's click/choice **to you, the AI** | **YES — this is the one you usually want** |
+| **2 — REVEAL A WINDOW** | `focus:{...}` | raises a window on the user's SCREEN (Hydrogen, a browser, a dialog) | **NO** — pure local desktop action |
+
+### Axis 1: how you get the answer back (there is NO server-push — you poll or you wait)
+
+You are turn-based; ab cannot inject an event into your conversation. So there are exactly two ways, fastest first:
+
+```bash
+# ⚡ FAST PATH — wait:true. The call BLOCKS and returns the user's choice inline.
+adom-bridge notify_user '{"title":"Ship v2 to prod?","scenario":"reminder","buttons":[{"label":"Ship it"},{"label":"Hold"}],"wait":true,"timeoutSec":120}'
+#   -> { "pending": false, "action": "Ship it" }
+
+# 🔁 FIRE-AND-CONTINUE — don't block; drain events on a later turn.
+adom-bridge notify_user '{"id":"deploy-42","title":"Ship v2?","scenario":"reminder","buttons":[{"label":"Ship it"},{"label":"Hold"}]}'
+adom-bridge notify_events '{"sinceSeq":0}'   # every click since a cursor (recommended: no per-id polling)
+adom-bridge notify_response '{"id":"deploy-42"}'   # or poll one id
+```
+
+The click is recorded **durably** (a cross-process file), so both paths work even on a headless VM where the toast is handled by a transient process. Details: sections 5 / 5b below.
+
+### Axis 2: `focus` (reveal a window) is NOT a reply
+
+`focus` is covered next. It raises a window on screen — it does **not** tell you anything. A toast can do BOTH at once (a sticky toast with buttons + `focus:{host:true}` reveals Hydrogen on click *and* reports the click back via `wait`/`notify_events`).
+
+## ⭐ Start here: make the click DO something (`focus`, v1.9.162)
+
+Most notifications are **about something else on screen** — a browser waiting on a login, a dialog, an app that needs a click. If you send a bare toast, clicking it opens the Adom Bridge window, which is almost never what the user wanted. They clicked because they wanted to get to *the thing*.
+
+Pass **`focus`** and one click takes them straight there:
+
+```bash
+adom-bridge notify_user '{
+  "title": "Sign-in needed",
+  "body": "Google wants you to confirm before I can continue.",
+  "focus": { "titleContains": "Sign in - Google Chrome" }
+}'
+```
+
+Three ways to name the window, in order of preference:
+
+| selector | when | note |
+|---|---|---|
+| `{"hwnd": 459604}` | **best** — you already have the handle | exact. Get it from `desktop_list_windows`, or from whatever verb opened the window (`browser_open_window`, `launch`, ...). |
+| `{"cacheKey": "my-session-id"}` | you drove the window through a verb that cached it under a key | survives title churn, which a title match does not. |
+| `{"app": "hydrogen-desktop"}` | you know the owning APP, not the exact window | exe basename or friendly name, `.exe` optional, case-insensitive. **Survives PID churn** — a process that restarts keeps its exe name — so it beats a stale `hwnd` for a long-lived app that respawns. |
+| `{"host": true}` | the notification is a prompt/approval ab is showing **on behalf of Hydrogen** | ⭐ "the app ab is embedded under." ab resolves Hydrogen's window itself — you don't need Hydrogen's hwnd or title. A click reveals **Hydrogen**, not ab. No-op (falls back to opening ab) when ab is standalone. **This is the fix for the embedded approval toast that used to open ab.** |
+| `{"titleContains": "Sign in"}` | you only know roughly what it says | substring, case-insensitive. Breaks the moment the title changes — and page titles change constantly. |
+
+ab resolves the target **when you send** and tells you in the response whether the click will land:
+
+```json
+"clickBehavior": "focus-window",
+"focus": { "resolved": true, "hwnd": 1313916, "title": "Sign in - Google Chrome", "resolvedBy": "title" }
+```
+
+`resolved:false` means no matching window exists **right now**. The toast still shows, and ab re-resolves at click time using the selectors you passed — so this is fine if the window has not been created yet, and a bug you should fix if it should already exist. If it still cannot find the window on click, it falls back to opening Adom Bridge rather than doing nothing.
+
+**Rule of thumb: if your notification mentions a window, a browser, a dialog, a tab, or asks the user to go click something, it should carry `focus`.**
+
+## Fields
+
+| field | type | notes |
+|---|---|---|
+| `title` | string | bold top line. Optional as of 1.9.123 (missing/null renders as empty). |
+| `body` | string | message text (use `\n` for a second line). Optional as of 1.9.123 — a progress toast needs no body. ⚠ Against a PRE-1.9.123 ab, an omitted body made the whole notify TIME OUT with no toast (the CLI sent `"body": null`, which failed the GUI's parse and the error was silently dropped); if you hit `status:timeout` on an old ab, add any `body` string. |
+| `level` | string | `info` (default) · `success` · `warning` · `error` · `emergency`. `warning`/`error`/`emergency` auto-use the long (~25s) duration; `emergency` also flashes the taskbar. (Windows owns toast chrome — `level` does not colour the toast; use `scenario`/`durationLong` for emphasis.) |
+| `durationLong` | bool | force the ~25s duration even for info/success |
+| `scenario` | string | `reminder` / `alarm` / `incomingCall` → **STICKY**: the toast stays on screen until the user acts (no auto-dismiss). Requires at least one button. |
+| `buttons` | array | `[{ "label": "...", "arguments": "<optional uri>" }]` — action buttons. Omit `arguments` and ab synthesizes a round-trip URI so a click is reported via `notify_response` (below). |
+| `actions` | array | back-compat: `["Label1","Label2"]` — simple label-only buttons (same round-trip as `buttons` without `arguments`). |
+| `progress` | object | `{ "title":"...", "value":0.0-1.0, "status":"...", "valueOverride":"6 / 10" }` — a live progress bar. Omit `value` for an indeterminate bar. |
+| `inputs` | array | `[{ "id":"reply", "type":"text", "placeholder":"..." }]` or `{ "type":"selection", "title":"...", "choices":["a","b"] }`. **Display only** — see Limitations. |
+| `id` | string | correlation id. Supply it so you can poll `notify_response {id}` for the clicked button. Auto-generated if omitted (and returned to you as `id`, so you can still poll it). |
+| `focus` | object | ⭐ `{hwnd}` \| `{cacheKey}` \| `{titleContains}` \| `{app}` \| `{host:true}` — the window this notification is ABOUT. A body click brings **that** window to the front instead of opening ab. `{app:"<exe/name>"}` targets any app by owning process (survives PID churn); `{host:true}` targets the app ab is embedded under (Hydrogen). See the section above. |
+| `wait` | bool | block the verb until the user clicks (or `timeoutSec` elapses) and return their choice, instead of polling `notify_response`. Needs buttons (or a `focus` click) to be meaningful. **Only actually works as of v1.9.162** — the field existed and was documented long before anything implemented it. |
+| `timeoutSec` | number | how long `wait` blocks, 1-600. Default 60. |
+
+**`wait:true` + `buttons` is a DECISION PROMPT and is mirrored like a permission prompt (v2.1.48, wiki #157).** Besides the toast, ab pushes it onto its own in-window permission stack, to Hydrogen's dialog when embedded, and to every same-account mesh peer's stack, with your button labels as the choices. The first answer on any surface is THE answer: it comes back as `{action:"<label>"}` exactly as a toast click would, and every other copy is dismissed. So a bridge consent gate (`pup_credential_reveal`, `pup_fill_card`, `pup_vault_sync`) still reaches the user on a box that blocks Windows toasts, with no bridge-side change. Send a structured `reason` so the mirrored card can show it ("The AI says: ...").
+
+## The types — copy/paste
+
+**1. Basic** (auto-dismiss ~7s)
+```bash
+adom-bridge notify_user '{"title":"Export done","body":"gerbers.zip is ready."}'
+```
+
+**2. Level + long duration** (warning/error stay ~25s; emergency also flashes the taskbar)
+```bash
+adom-bridge notify_user '{"title":"DRC failed","body":"3 clearance violations.","level":"error"}'
+```
+
+**3. Sticky reminder** — stays until the user clicks (the "please acknowledge" type)
+```bash
+adom-bridge notify_user '{"title":"Review needed","body":"The board is ready for your sign-off.","scenario":"reminder","buttons":[{"label":"Acknowledge"}]}'
+```
+
+**4. Progress bar** — perfect for a long export
+```bash
+adom-bridge notify_user '{"title":"Exporting gerbers","progress":{"title":"InstaPCB","value":0.6,"status":"Working...","valueOverride":"6 / 10 layers"}}'
+```
+Re-fire with the SAME `id` to update the bar as the job advances; set `value` toward `1.0`.
+
+**5. Buttons that round-trip** — learn which one the user clicked
+```bash
+# Fire with a correlation id you choose:
+adom-bridge notify_user '{"id":"approve-42","title":"Deploy v2?","body":"Ship to prod?","scenario":"reminder","buttons":[{"label":"Ship it"},{"label":"Hold"}]}'
+
+# Then poll until the user acts (pending:true until they click):
+adom-bridge notify_response '{"id":"approve-42"}'
+#   pending → { "pending": true,  "action": null }
+#   clicked → { "pending": false, "action": "Ship it" }
+```
+Poll every 1–2s; give up after a sensible timeout (the user may dismiss it).
+
+The click is recorded **durably** (a cross-process file), so `notify_response` works even when the toast activation is handled by a transient process (e.g. a headless VM) — not just when ab is in the foreground (v1.9.104).
+
+**5b. Get told without per-id polling — `notify_events`** (v1.9.104)
+```bash
+# One call returns EVERY click since your cursor (relay has no true server-push,
+# so this is the "tell me immediately" path — poll it, not notify_response per-id):
+adom-bridge notify_events '{"sinceSeq":0}'
+#   → { "events": [ { "event":"notify_clicked", "id":"approve-42", "action":"Ship it", "at":"..." } ],
+#       "nextSeq": 1, "count": 1 }
+# Pass the returned nextSeq as sinceSeq next time to get only new clicks.
+```
+
+**5c. Retract a sticky toast — `notify_dismiss`** (v1.9.104)
+```bash
+# Clear a scenario:"reminder" (never-expires) toast from the notification center
+# once you've handled it — by the same correlation id you fired it with:
+adom-bridge notify_dismiss '{"id":"approve-42"}'   # → { "dismissed": true }
+```
+
+**6. Explicit button URI** — drive an arbitrary action (advanced)
+```bash
+# A button can carry any adom-bridge:// URI; clicking launches it + foregrounds ab.
+adom-bridge notify_user '{"title":"...","buttons":[{"label":"Approve 1 hr","arguments":"adom-bridge://shell-approve?dur=3600"}]}'
+```
+
+**7. Point the user at the window that needs them** (the most useful type, v1.9.162)
+```bash
+# The whole notification is "go look at this" — so make the click go there.
+HWND=$(adom-bridge desktop_list_windows | jq '.windows[]|select(.title|test("Sign in"))|.hwnd')
+adom-bridge notify_user '{"title":"Sign-in needed","body":"Confirm in the browser and I will continue.","focus":{"hwnd":'"$HWND"'}}'
+```
+Add `scenario:"reminder"` + a button if you also need to know they dealt with it. A focus click is itself recorded as an acknowledgement (`action:"focus"`), so `notify_response`/`notify_events` tell you they engaged even with no buttons at all.
+
+## Click behaviour — what actually happens
+
+Clicking the toast **body** or any **button** activates ab's `adom-bridge:` URI protocol, which dispatches the action through ab's single-instance handler (reliable since v1.9.33; the protocol path is deliberately COM-activator-free, see the WIN11 notes in the repo).
+
+What a **body** click does depends on you:
+
+| you sent | body click does |
+|---|---|
+| `focus: {...}` | **brings that window to the front.** Falls back to opening ab if the window is gone. Also records `action:"focus"` under your `id`. |
+| nothing | opens the Adom Bridge window. Rarely what the user wanted. |
+
+A **button** click does what its `arguments` URI says, defaulting to a round-trip that reports the label back through `notify_response`. Buttons do **not** foreground ab (v1.9.146) — a toast exists to reach someone *without* interrupting them, so acknowledging one must not yank them out of what they were typing. The exceptions are deliberate: a body click (the conventional "show me the app" gesture) and a shell-approval grant (you should see what you just authorized).
+
+### What a click can and cannot be wired to
+
+`focus-window` is exposed as a click action; **arbitrary verbs are not, and will not be.** The reason is that you write both the button label and its URI, so a button could always be mislabelled. Only actions whose worst case is tolerable under *any* label belong on a toast: raising a window is non-destructive, immediately visible, and undone by one alt-tab. Anything that executes, writes, or grants is not — that is what the permission model is for.
+
+## The response teaches you (v1.9.162)
+
+Every `notify_user` response carries what a click will do and what to do next:
+
+```json
+{
+  "status": "ok", "action": "displayed", "id": "t-42",
+  "clickBehavior": "focus-window",
+  "focus": { "resolved": true, "hwnd": 1313916, "title": "...", "resolvedBy": "hwnd" },
+  "_hint": "Shown. Clicking the notification brings \"...\" to the front ...",
+  "_next": [ "notify_response {\"id\":\"t-42\"}", "notify_events {\"sinceSeq\":N}", "desktop_list_windows" ]
+}
+```
+
+When the call left something on the table you also get **`_couldHaveDoneBetter`** (specific, e.g. "no `focus` was passed, so clicking this just opens Adom Bridge") and **`_capabilities`** (the full menu of what `notify_user` can do). These appear **only when there is something to fix**, so a well-formed call gets a short response and you are not charged tokens to be told things you clearly already know. Read them the first time and you will not see them again.
+
+Current coaching triggers:
+- no `focus` (with an extra nudge when the wording sounds like it is asking the user to go do something)
+- `focus` that resolves to no window right now
+- buttons without `scenario:"reminder"` (auto-dismisses in ~7s, the user may never see it)
+- `wait:true` with nothing to click
+
+## Limitations (Windows toast rules — not ab bugs)
+
+- **Typed `inputs` are display-only for now.** Protocol activation (what makes button clicks reliable + foreground ab) does NOT carry the toast's typed text / selection back to ab. For a real choice round-trip, use **buttons** (each choice = a button) and read `notify_response`. A free-text reply field renders but its value isn't delivered yet.
+- **A toast can't truly block.** Toasts are non-modal by Windows design, and Focus Assist / Do-Not-Disturb can route a normal toast straight to Action Center. For a hard, must-click-to-proceed prompt, that's a real dialog window, not a toast.
+- **`scenario:"reminder"` needs a button** or Windows may auto-dismiss it anyway.
+
+## Troubleshooting — "I got `status:ok` but saw no toast"
+
+`notify_user` returning `status:ok` currently means only *"ab accepted the request and spawned the toast"* — it is **fire-and-forget and does NOT confirm the toast displayed** (known gap, 2026-06-28). If a toast doesn't appear:
+1. **Check the Action Center (Win+N).** If it's sitting there, **Do Not Disturb / Focus Assist** routed it (a successful `Show()` with notifications *Enabled* still goes straight to the center under DND — verified 2026-06-28: a diag toast showed `SHOW_OK notifier.Setting=Enabled` yet popped no banner; it was in the Action Center). That's a Windows setting, not an ab bug. **To make ab toasts pop through DND**, the user adds Adom Bridge to the Focus-Assist allow-list: **Settings → System → Notifications → Set priority notifications → add "Adom Bridge"**. Windows won't otherwise let an app force a banner past DND — so ab itself can't bypass it; it's a one-time user toggle.
+2. **Check you are actually reaching that ab.** From a cloud container, `notify_user` traverses the relay the ab is connected to; a `--target <name>` aimed at a relay that isn't running silently fails, so confirm with `adom-bridge targets` first. (The **direct API does** carry notify as of v1.9.84 — a bridge or sibling app on the same machine can `POST /command {"command":"notify_user",...}` — so a local caller does not need the relay.)
+3. When you must be *sure* the human saw it, don't rely on the toast alone — also surface the message in your chat/response.
+
+## When to use which
+- **Awareness** ("export done", "build green") → basic, or `level:"success"`.
+- **"Go look at this"** (a login, a dialog, an app waiting on them) → **`focus`**, so the click lands on that window. This is the single highest-value field in the verb and the one most often forgotten.
+- **Needs attention but not blocking** → `level:"warning"` (long duration) or `scenario:"reminder"` so it persists.
+- **Long-running job** → `progress` bar, re-fired with the same `id`.
+- **Need the user to choose** → `scenario:"reminder"` + `buttons` + poll `notify_response` (or `wait:true` to block).
+- **Genuine emergency** → `level:"emergency"` (long + taskbar flash).
+
+## Version notes
+- **2.1.48** — a `wait:true` + `buttons` notify is mirrored to ab's permission stack, Hydrogen and the mesh peers (button labels = choice ids); first answer anywhere resolves it and dismisses the rest (wiki #157: boxes that block toasts).
+- **1.9.167** — `focus:{app}` (target any app by owning process, survives PID churn) + `focus:{host:true}` (reveal the app ab is embedded under — Hydrogen). The fix for the embedded approval toast that opened ab instead of Hydrogen: Hydrogen (or an AI prompting on Hydrogen's behalf) passes `focus:{host:true}`. Also: the two-axis framing at the top, because the get-the-answer-back path (`wait`/`notify_events`) was being confused with the local-reveal path (`focus`).
+- **1.9.162** — `focus` (click-to-focus) + the `_couldHaveDoneBetter` coaching. Also fixed: the CLI used to rebuild the notify payload from an allowlist and silently drop anything not on it, so the documented `wait`/`timeoutSec` never reached ab at all. It now forwards every field verbatim.
+- **1.9.146** — button clicks no longer foreground ab (they used to interrupt whatever you were typing).
+- **1.9.123** — `title`/`body` are optional; a null body used to make the whole call time out.
+- **1.9.104** — durable click recording + `notify_events` + `notify_dismiss`.
+- **1.9.33** — protocol activation: clicks became reliable; progress/sticky/buttons/inputs added.
+
+## onClick: the toast body click runs a verb (v2.0.98)
+
+"Whenever I see dialogs like this I always want to click on them and have them do something
+of value rather than take me back to your main UI" (John). `focus` covers raise-a-window;
+`onClick` covers everything else:
+
+```json
+notify_user {
+  "title": "Your export finished",
+  "body": "Click to open the folder",
+  "id": "export-42",
+  "onClick": {"command": "open_url", "args": {"url": "file:///C:/exports"}}
+}
+```
+
+- `onClick: {command, args?, app?}` arms a pre-declared ab VERB on the toast's BODY click.
+  It takes precedence over `focus`. One-shot: the first click consumes it.
+- **It runs AS YOU, through YOUR normal gates.** Your transport origin and identity are
+  captured at send time and replayed at click time, so a gated verb (shell_execute,
+  run_script) surfaces the standard human approval when clicked instead of running. A
+  click is a trigger, never a grant: the action can never exceed what you could have done
+  by calling the verb directly. Deliberately a verb, never a script blob; script-shaped
+  work rides as run_script behind its own gate.
+- **The user sees feedback**: a small bottom caption shows "Toast click: running <verb>..."
+  the moment they click, then "Done: <verb>" or the failure with a short error. A failed
+  click is never invisible.
+- **You get the result**: it lands in `notify_response {id}` under `action: "onClick"`
+  with ok/errorCode/error. Poll it (or notify_events) to learn what happened.
+- Verb names must be CURRENT: the first live demo armed a pre-rename verb and the click
+  recorded verb_renamed. If a rename refusal comes back, re-arm with the new name.
+- An expired or already-used click falls back to raising Adom Bridge, never a dead click.

@@ -0,0 +1,85 @@+---+name: adom-bridge-bridge-ownership+description: The boundary between Adom Bridge core and a bridge author — what ab owns vs what you (the bridge) own. Read before filing an ab bug about a bridge (kicad, fusion360, native-browser, puppeteer, blender, rdp, or any third-party bridge) or before editing bridge code, so you fix and report in the right place.+---++# Who owns what: ab core vs bridge author++**Read this FIRST if you're working on, debugging, or filing a bug about a bridge+(kicad, fusion360, native-browser, puppeteer, blender, rdp, or any third-party+bridge).** It exists because an AI drove the Fusion bridge end-to-end, hit a dozen+issues, and filed almost all of them against **adom-bridge** — when nearly every+one was **bridge code**. The platform never stated the boundary, so the AI guessed+"ab," posted to the wrong place, and hand-edited the wrong copy. Don't repeat that.++## The split++### Adom Bridge (ab) core owns+- The `adom-bridge` CLI + the **relay / `/command` passthrough** (ab relays a+  bridge's response **verbatim** — incl. `_hint`/`_next`/`related` and every other+  top-level field the bridge sets; v1.9.30 made this a denylist, never an allowlist).+- **Bridge lifecycle**: discover/register/spawn/reap, stable ports, the+  `bridge_*` verbs, and **streaming a bridge from its wiki page into the local+  cache** (`bridge_install` / `refresh_bridges` / the 4-h auto-sync).+- The core `desktop_*` verbs (input, screenshot, UIA, tunnels, wsl, …).+- Generic, app-agnostic behavior. **ab returns good DATA so the calling AI decides+  — it does NOT bake in app-specific verbs** (see CLAUDE.md "ab stays GENERIC").++### The bridge author owns (NOT ab)+- **Every bridge-specific verb and its behavior** — args, outputs, and the per-call+  `_hint`/`_next`/`related`/`pitfalls` (the rich-hint contract). A wrong/missing+  hint is a **bridge** fix.+- **Any integration the bridge ships** — e.g. Fusion's **APS** cloud search: its+  OAuth/auth, its config, its `*_aps_*` verbs, its never-charge caps. ab does NOT+  manage it. Divergent results from the bridge's own status verb = a **bridge** bug.+- **The bridge's add-in / plugin code AND getting it deployed into the host app.**+  Editing the streamed cache source is not enough if the host app loads the add-in+  from elsewhere (e.g. Fusion loads from `%APPDATA%\…\API\AddIns\`, not the+  bridges-cache) — wiring cache→host-app is the **bridge's** concern.+- The bridge's `SKILL.md`, `describe` verb, hero/wiki page, and version.+- The **edit-source → publish → bump version → reinstall** loop.++## The cardinal rules++1. **NEVER hand-edit the streamed cache** (`%LOCALAPPDATA%\Adom Bridge\bridges-cache\<bridge>\`).+   It's a download. Edit the **source** (the bridge's own repo/wiki), `publish`,+   bump the version, then `bridge_install`/`refresh_bridges` to pull it. A+   hand-edit is overwritten on the next sync and may not even be what the host app+   runs (cache-vs-deployed-copy gotcha).+2. **Before filing a bridge bug against adom-bridge, ask "who owns this?"** If it's+   verb behavior, a hint, an integration, an add-in, or the bridge's docs → it's the+   **bridge author's** repo/wiki, not ab. Cloud-owned bridges (kicad, fusion, puppeteer)+   live in their OWN wiki repos (see CLAUDE.md "Cloud-owned bridge repos").+3. **ab's job is to relay + host, generically.** If ab is *dropping* or *mangling*+   a bridge's data, or missing a lifecycle/verb capability — THAT is an ab bug.+   Fix the ab VERB; don't re-absorb the bridge.++When in doubt: data-shape/relay/lifecycle/ports → **ab**; what a verb does, its+hints, its integration, its add-in, its docs → **the bridge**.++## Skill ownership — a bridge ships its OWN skill pkg (not bundled in ab-core)++The same boundary applies to the **consumer skill** (the SKILL.md that teaches a cloud+container how to drive a bridge's verbs):++- **The ab-core pkg** (`adom-wiki pkg install adom/adom-bridge`) ships ONLY core skills —+  desktop verbs, discovery, direct-api, installer, notify, multi-ad, bridge-sdk,+  bridge-ownership, windows-host. It must NOT bundle a cloud/3rd-party bridge's skill (it+  would go stale and isn't ab's to own). (2026-06-28: `eagle-commands.md` — Fusion-Electronics,+  `fusion_electron_run` — was dropped for this reason; 2026-06-29: `pup-SKILL.md` was dropped+  too when Puppeteer became cloud-owned. Both belong in their bridge's own pkg.)+- **Each cloud/3rd-party bridge publishes its OWN skill pkg** carrying its SKILL.md, e.g.+  `adom/kicad-bridge`, `adom/fusion-bridge`,+  `adom/pup-bridge`. The cloud thread that owns the bridge owns + bumps it.+  (Puppeteer's runtime still ships as an NSIS-bundled SEED for fresh-PC/offline spawn — but its+  *skill* now ships from its own page, like the other cloud bridges.)+- **How a container gets dynamic bridge skills:** it does NOT get them from the ab-core install.+  It (a) installs ab-core (CLI + core skills), then (b) `adom-bridge bridge_list` against the+  live laptop ab to see which bridges are present, then (c) `adom-wiki pkg install+  adom/adom-bridge-<bridge>-bridge` for each one it needs (and `adom-wiki pkg update` keeps them+  fresh, version-matched to the bridge the cloud thread published). The bridge's runtime PAYLOAD+  (what ab spawns on the laptop) is a SEPARATE artifact — the `/files` manifest+zip that+  `bridge_install`/`refresh_bridges` pull — don't conflate it with the skill pkg.+- **Discoverability gap / enhancement:** `bridge_list` should surface the exact+  `adom-wiki pkg install adom/adom-bridge-<name>-bridge` line per live bridge so a container+  knows precisely which skill pkg to pull (today it infers the slug from the bridge's `docs`).

@@ -0,0 +1,158 @@+---
+name: adom-bridge-permissions
+description: >
+  How the Adom Bridge human-approval permission gate works for an AI caller.
+  Read this when a verb refuses with errorCode needs_approval or reason_required,
+  when you need shell approval / bypass permissions on a machine, when you must
+  call request_shell_approval to surface the human approval dialog, when a call
+  demands a reason arg, or before an unattended run that touches shell_execute,
+  run_script, write_file, or any other gated verb. Covers the human approval
+  gate, the Approve 1 hr / 24 hr / Bypass Permissions buttons, and why grants
+  are human-only.
+---
+
+# Adom Bridge permissions — the human approval gate for AI callers
+
+## The trust model in one paragraph
+
+ab binds `127.0.0.1` only, and installing ab (or a bridge) is the user's consent to be driven — so every LOCAL caller (the CLI on the same box, Hydrogen, and bridges on the loopback direct API) is **trusted by transport and never gated**. The approval gate applies to exactly one origin: the **remote relay / cloud-AI path** (`via_relay`) — a thread driving the machine from off-box that the user may not be watching. If you are calling over the relay, the gated verbs below require a human grant. Read-only verbs (screenshots, status, window and UI reads, discovery) are never gated.
+
+## Which verbs gate
+
+The gated class is "runs code / writes / deletes / modifies registry or persistence / kills processes / synthesizes input":
+
+- **Arbitrary code execution:** `shell_execute`, `run_script`, `launch_process`, `wiki_exec`, and the WSL write/exec verbs (`wsl_exec`, `wsl_exec_async`, `wsl_import`, `wsl_export`, `wsl_unregister`)
+- **Filesystem:** `write_file`, `delete_file`
+- **Registry:** `registry_set`, `registry_delete`
+- **Process control:** `process_kill`
+- **App identity / shell integration:** `register_app_identity`, `unregister_app_identity`, `set_window_jumplist`
+- **Synthetic input** (drive the machine as the user): `desktop_click` / `type` / `press_key` and the UIA action verbs — these ride the SAME grant window as shell
+
+One human grant covers the whole class. A bridge's own exec verbs (`pup_evaluate`, `nbrowser_eval`, `blender_run_python`, `fusion_run_modeling_script`, ...) gate per that **bridge's declared `risk` class** (v2.0.84, wiki #50): a bridge that declares a gated class (`exec`/`write`/`network`/`browser-drive`/`config`/`process`/`registry`) has its verbs gated for RELAY callers exactly like a shell verb; a bridge that declares `read` or nothing is ungated. This is **opt-in** — a bridge with no declaration behaves as before. The precise per-verb source is that bridge's describe output; the manifest `risk` is the bridge-wide floor. So: still check the bridge's describe for the exact per-verb answer, but the gate is now real.
+
+## The `reason` requirement — every gated call must explain itself
+
+Every permission-class verb sent over the relay MUST carry a `reason` arg: one plain sentence saying WHY you need this. The human sees it verbatim in the approval prompt, attributed as **"The AI says: ..."** (omitting it shows "(no reason given)", which a cautious user should decline). It also lands in ab's activity log.
+
+```bash
+adom-bridge shell_execute '{"command":"winget install --id KiCad.KiCad -e",
+  "reason":"Installing KiCad so I can export your gerbers"}'
+```
+
+Write the reason for the human, not for the log: say what you are trying to accomplish, not what the command does. Good: `"Installing the KiCad CLI so I can export your gerbers"`. Weak: `"running npm install"` (that is just the command again). The reason is capped at 300 chars and never replaces the command preview — the human always sees both.
+
+A permission-class call with NO reason is refused before any approval path:
+
+```json
+{
+  "success": false,
+  "errorCode": "reason_required",
+  "error": "'write_file' needs human permission, so it REQUIRES a `reason`. Retry the SAME call with reason:\"...\".",
+  "retryWith": { "reason": "<why you need this, in one plain sentence>" },
+  "appliesTo": ["shell_execute", "run_script", "launch_process", "wiki_exec", "write_file", "..."]
+}
+```
+
+The rule is class-based and flat: the verbs in `appliesTo` ALWAYS carry a reason (whether or not a grant is currently active); verbs not in that list never need one. Learn it once — do not pay the round-trip again, and do not add `reason` to ungated verbs.
+
+## What a refusal looks like
+
+When no grant is active, a gated relay call refuses with `errorCode: "needs_approval"` plus a structured `approval` block — you never need to read `~/.adom/config.json`:
+
+```json
+{
+  "success": false,
+  "errorCode": "needs_approval",
+  "error": "'write_file' needs shell approval — it runs code / writes / deletes / modifies the registry / kills a process (a Tier-2 verb, as dangerous as shell_execute).",
+  "approval": {
+    "required": true,
+    "granted": false,
+    "class": "shell",
+    "verb": "write_file",
+    "grantedBy": "human-only",
+    "grantVerb": "request_shell_approval",
+    "howToGrant": ["Ask the user to click Approve (1 hr / 24 hr) or Bypass Permissions ...",
+                   "Call request_shell_approval to re-surface the prompt ...",
+                   "The user can tick Settings > Shell Commands > Bypass Permissions ..."]
+  }
+}
+```
+
+The refusal itself already surfaced a human-facing prompt on the machine: the in-window `#shell-approval` dialog, an actionable Windows toast, and a taskbar flash. If the human actively clicks Deny, you get `errorCode: "denied_by_user"` instead — do NOT auto-retry that one; ask the user what they want.
+
+## The correct AI flow on a gate hit
+
+1. **Surface the prompt** (the gate already did once; re-surface on demand):
+
+   ```bash
+   adom-bridge request_shell_approval
+   ```
+
+   This is ungated — it only SURFACES, never grants. It re-shows the in-window approval dialog, fires the toast, and brings ab to the front, so "there is nothing to click" is never true.
+
+2. **Ask the human** (in your conversation) to click **Approve 1 hr**, **Approve 24 hr**, or **Bypass Permissions** in the Adom Bridge window or on the toast.
+
+3. **RETRY the original verb unchanged** (with its `reason`). One grant covers the whole exec/write/registry/kill/input class for the granted window.
+
+## Grants are HUMAN-ONLY — you cannot self-grant
+
+Granting is permanently human-only. The only grant paths are a human clicking in ab: the in-window dialog's Approve buttons, the toast's `adom-bridge://shell-approve` buttons, and the Settings checkbox. A GRANT attempt via `shell_auto_approve` / `set_shell_auto_approve` from a relay (cloud-AI) caller is **refused with `errorCode: "human_only"`** and auto-surfaces the human prompt instead. Your only lever is `request_shell_approval` — it TRIGGERS the human decision; it does not perform it.
+
+The one exception: a **REVOKE is allowed for any caller** (de-escalation is always safe):
+
+```bash
+adom-bridge shell_auto_approve '{"duration_secs":0}'   # clears the checkbox AND the timer
+```
+
+Do not look for a workaround. `launch_process` is not a bypass of `shell_execute` (it gates identically), and synthetic input (clicking the Approve button yourself) rides the same grant. If the AI could grant, the gate would be theater.
+
+## The durable Settings checkbox
+
+**Settings > Shell Commands > Bypass Permissions** (config `shell_auto_approve_permanent`, default OFF) is the durable indefinite grant, for machines the user fully trusts. The timed buttons (1 hr / 24 hr) set an in-memory window instead. Unticking the checkbox, or `shell_auto_approve {"duration_secs":0}`, returns to per-command approval instantly.
+
+## Embedded mode changes nothing for you
+
+ab owns approvals in every mode. When ab runs embedded under Hydrogen it still shows its OWN ab-branded dialog and toast and makes its OWN decision — Hydrogen is only a display surface. As a mirror, ab also fire-and-forgets the request to Hydrogen so Hydrogen can raise its own prompt, so the user may see two prompts (ab's and Hydrogen's) for one request; either one resolves it. Hydrogen stores no approval state and cannot pre-authorize or force a decision. The `auto_approve` field older Hydrogen versions send is now accepted and ignored.
+
+As of v2.1.18 (wiki #137) this mirroring covers EVERY consent surface, not just the shell gate: web-control consent, credential import, and the desktop input / UIA / clipboard approval prompts all appear in Hydrogen too when ab is embedded — so a user who blocks Windows notifications still sees each request somewhere. The input-class refusal also now raises ab's own in-window dialog + toast (it used to refuse silently with JSON only), so "there was no prompt anywhere" should never be true again.
+
+From your side as the relay caller there is nothing different to do: the same `errorCode` values, the same `request_shell_approval` re-surface, the same "ask the human, then retry" flow. Do not treat embedded mode as a separate case.
+
+Two facts about STACKED prompts worth planning around: (1) ab holds at most ONE pending shell approval at a time - a second gated shell command while one is waiting is rejected immediately (anti-spam), so do not fire gated commands in parallel; wait for the first decision, or ask for a grant up front. (2) When decisions do pile up across surfaces, ab shows THE PERMISSION STACK (v2.1.24): one "Permission requests" panel where every pending consent - shell, grant request, web page, credential - is a card in one design language (kind chip, requester, decoded command, attributed reason, buttons from the same per-gate choices tables the toasts and the Hydrogen mirror use). Newest card expanded, the rest collapsed rows; deciding one promotes the next. ONE grant click (1 hour / 24 hours / Auto) on any surface still approves every waiting shell request at once and clears all the toasts - a returning user needs one click, not a click per prompt.
+
+## Check state up front with `status`
+
+Before an unattended run, read `status.permissions.shell` so you know whether you will stall on a human gate:
+
+```bash
+adom-bridge status
+```
+
+```json
+"permissions": {
+  "shell": {
+    "autoApproved": false,
+    "willPrompt": true,
+    "source": "none",              // "permanent" | "timed" | "none"
+    "expiresInSec": null,
+    "grantedBy": "human-only",
+    "grantVerb": "request_shell_approval",
+    "gatedFor": "relay (cloud-AI) callers only",
+    "embedded": false              // true = ab is under Hydrogen, but ab still decides
+  },
+  "bridgeExec": { "note": "gated by ab per the bridge's declared `risk` class (v2.0.84, issue #50): a gated class (exec/write/network/browser-drive/config/process/registry) prompts a RELAY caller like shell; `read`/undeclared is ungated (opt-in). Per-verb precision is in the bridge's describe output." }
+}
+```
+
+If `willPrompt` is true and no human is at the machine, get the grant FIRST (`request_shell_approval` + ask the user) before starting the run.
+
+## Quick reference
+
+| Situation | What you do |
+|---|---|
+| `errorCode: reason_required` | Resend the SAME call plus `reason:"<one plain sentence>"` |
+| `errorCode: needs_approval` | `request_shell_approval`, ask the human to click Approve, retry |
+| `errorCode: human_only` | You tried to self-grant. Ask the human instead |
+| `errorCode: denied_by_user` | The human said no. Do not auto-retry; ask them |
+| Planning an unattended run | Check `status.permissions.shell.willPrompt` first |
+| Need to drop a grant | `shell_auto_approve {"duration_secs":0}` (allowed for any caller) |

@@ -0,0 +1,139 @@+---+name: adom-bridge-presence+description: How Adom Bridge lives quietly on the machine. Covers the system tray and close-to-tray behavior (the X button hides the window, ab keeps serving), the low-memory hidden-window mode (WebView2 suspension while hidden), launch on boot (default ON, Startup-shortcut self-heal), and the taskbar icon states (muted "Adom Bridge" standalone tile vs vivid "Adom Bridge Hydrogen Embedded" tile, the AUMID flip). Use when a user or AI asks why ab is still running after closing the window, why memory is low while hidden, how to tell standalone from embedded mode from the taskbar alone, how to enable or disable launch on boot, why the tray icon is missing, or what the window title markers mean.+---++# Adom Bridge presence: tray, hidden window, taskbar states++ab is a tray-resident app. Its window is hidden most of its life; the working+core is a small native (Rust) process that keeps serving the relay, direct API,+bridges, toasts, and approvals whether or not the window is on screen.++## Close to tray: X hides, ab keeps serving++- Clicking the window's X does NOT exit ab. The close request hides the window+  and ab keeps running and serving (relay, direct API, bridges, notifications).+  This is by design: ab must stay reachable as the machine's recovery channel.+- It is never silent: the FIRST 3 TIMES the user hits X, ab shows a toast+  explaining that it moved to the tray, then stops reminding. The counter lives+  at `~/.adom/tray-notice-count` (a legacy one-shot `tray-notice-shown` file+  seeds the count at 1 so existing users are not re-nagged from scratch).+- Launching ab again while it is hidden is never a no-op (single-instance):+  - standalone: the existing instance shows and focuses its window+  - embedded with Hydrogen alive: a toast says where ab lives (inside Hydrogen)+  - embedded but Hydrogen is dead (stale flag): treated as standalone, window shows+- The ONLY thing that exits ab is the `desktop_shutdown` verb+  (`POST /command {"command":"shutdown"}` on the direct API). Closing the+  window never does.++## The tray icon: standalone only++- In STANDALONE mode ab has a system tray icon.+- When EMBEDDED in Hydrogen, ab HIDES its tray icon. The tray can+  therefore never signal the embedded state; the taskbar tile does (below).+- Do not "fix" a mode-signal question by looking at (or swapping) the tray+  icon; in embedded mode there is none.++## Low-memory hidden-window mode (v1.9.135, `src/webview_lowmem.rs`)++The problem it solves: a hidden GUI used to cost the same as a visible one+(about 470 MB of WebView2 on top of the roughly 60 MB Rust process), because a+window-level hide never flips the WebView2 controller's visibility, so the+renderer kept full-power compositing into an invisible window.++What happens while the window is HIDDEN:++- A watcher polls main-window visibility every 3 seconds (there is no Tauri+  visibility event; polling catches every hide/show path).+- Hidden: the WebView2 controller is set invisible (`SetIsVisible(false)`),+  the memory target drops to LOW (`SetMemoryUsageTargetLevel`), and the page+  is suspended (`TrySuspend`).+- GPU flags are trimmed: `--disable-gpu --disable-gpu-compositing` are merged+  into the WebView2 browser arguments on real desktops (gpu-process measured+  151 MB down to 68 MB; renderer sandbox and code integrity stay ON).+- UI-only work is skipped: the 15 second health loop's LED probes and+  `bridge-status` emits exist only to paint the GUI, so they are gated on+  visibility. Every Tauri emit is an `evaluate_script`, which auto-resumes the+  page by WebView2 design, so the watcher also re-suspends every ~60 seconds+  to mop up resumes caused by command-driven activity-log emits.+- The Rust side keeps doing ALL real work, ungated: relay, direct API,+  bridges, bridge supervision (persistent respawn plus duplicate collapse),+  toasts, tray, shell approvals. Only the GUI panel is affected.++What happens when the window is SHOWN again:++- The controller becomes visible again, the page resumes, and the memory+  target returns to NORMAL. Full power, immediately.+- LEDs self-heal on the first visible health tick, within about 15 seconds+  of show.+- A shell-approval flow shows the window, which flips everything back to full+  power on its own.++Escape hatches (diagnosis only): `ADOM_LOWMEM=0` disables the watcher;+`ADOM_WEBVIEW_GPU=1` keeps hardware GPU.++## Launch on boot: default ON, self-healing (v1.9.126)++- The intent is `config.launch_on_boot`, DEFAULT TRUE. The Settings checkbox+  ("launch on boot" / autostart) reads and writes this intent and is checked+  by default.+- A reconcile runs on EVERY launch, in BOTH standalone and embedded modes:+  - intent ON and the shortcut is missing: create `AdomBridge.lnk` in the+    user's Startup folder (with the `--autostart` arg)+  - intent OFF and the shortcut exists: delete it+- This is the self-heal: a shortcut that was never created, got deleted, or+  failed to write is recreated on the next launch. It runs in embedded mode+  too, so ab comes up at boot even if Hydrogen's own autostart is off; the+  single-instance guard converges any double-launch to one embedded ab.+- The reconcile respects a Task-Manager-DISABLED startup entry+  (`StartupApproved\StartupFolder`); that is a deliberate user choice ab does+  not override.+- Never create startup shortcuts manually; the reconcile owns them.++## Taskbar icon states: the tile tells you the mode (v1.9.140)++Two registry-only Windows app identities (AppUserModelIDs) are registered at+every launch:++| Mode | AUMID | Taskbar name | Tile |+|---|---|---|---|+| Standalone | `Adom.Desktop` | Adom Bridge | MUTED teal (`#46817d`) |+| Embedded in Hydrogen | `Adom.Desktop.Embedded` | Adom Bridge Hydrogen Embedded | VIVID brand teal (`#00b8b0`) |++- Muted tile named "Adom Bridge" means ab is running on its own. Vivid tile+  named "Adom Bridge Hydrogen Embedded" means Hydrogen launched ab and is+  driving its lifecycle.+- The mode flip is an AUMID CHANGE on the main window, not a repaint: a live+  taskbar button's tile can never be repainted, but changing the window's+  AppUserModelID makes the shell destroy the old button and create a new one,+  which bakes its tile and name from the other identity's registration.+- Measured live: name AND tile flip in about 1 second, with no restart, no+  flicker, and no window hide. The new button forms at the end of the+  unpinned strip (buttons sit in creation order).+- Known cost: a taskbar pin binds ONE AUMID, so a pin made in one mode shows+  the running window as a SEPARATE button while ab is in the other mode.+  Documented and accepted.+- `inc.adom.bridge` (the toast and single-instance identity, carried by the+  one Start Menu launcher shortcut with the vivid brand icon) is never+  flipped; only the main window's per-window AUMID changes.++## Window title markers++The window title carries live trust and provenance markers:++- the running VERSION (for example `v1.9.140 release · ...`)+- a HOST vs SANDBOX context marker (whether this ab runs in the real host+  process namespace or inside an AppContainer sandbox shadow)+- a `signed` marker when the running exe carries a valid Authenticode+  signature++These are the quick truth check for "which build is actually running": the+relauncher's `verify_visible` step logs the full title, and the+`signed · HOST` combination is what a correctly deployed production ab shows.+(One caveat from the build system: the title's version string comes from a+compile-time constant that incremental builds can cache; the PE FileVersion+is the authoritative number when they disagree.)++## Foreground attribution (v1.9.175)++ab never raises its own window silently. Every self-foreground (sign-in completion, toast body click, shell-approve grant, `request_shell_approval`, tray menu, second launch) is logged to the Activity Log as a `foreground` event naming the source and reason, and to `startup.log` as a `FOREGROUND:` line. An update-apply relaunch is deliberately QUIET: the updater drops `~/.adom/update-quiet-relaunch` and the relaunched ab consumes it (10-minute freshness gate) and stays in the tray. If a user reports "ab randomly came to the front", read the Activity Log / startup.log — the answer is always recorded.

@@ -0,0 +1,148 @@+---
+name: adom-bridge-recording
+description: Record the user's screen with Adom Bridge's NATIVE recorder (v2.1.35, wiki #143) - desktop_record_start captures one monitor plus the system audio mix into an H.264/AAC MP4 with no browser and a persistent on-screen recording caption; desktop_record_window_* records a single window in the background; desktop_record_stop/status/list manage takes. Chrome screen-share recording (picker consent, WebM) is the puppeteer bridge's pup_screen_record_* - a different tool.
+---
+
+## v2.1.35: the native recorder (read this first)
+
+`desktop_record_start` is ab-core now. It records ONE MONITOR (`monitor`: index, `"primary"` or a device name; default primary) with Windows Graphics Capture and the SYSTEM AUDIO mix with WASAPI loopback, muxed to an H.264/AAC MP4 under `%TEMP%\adom-bridge-recordings\` on the desktop machine. No browser, no OS picker, no HUD process. Consent is a persistent caption at the top of the screen that stays for the whole take.
+
+- Start: `desktop_record_start {"monitor":0, "fps":30, "audio":true, "maxDurationMs":600000, "reason":"..."}` -> `{recordingId, path, encoder, hardwareEncoder, audio, audioNote?}`. `encoder` is the H.264 MFT Media Foundation chose; `hardwareEncoder:true` = NVENC / Quick Sync / AMF.
+- Stop: `desktop_record_stop {"recordingId"}` (id optional when one take is running) -> the finalized file, bytes, frames, audioFrames. Pull it with `pull_file`.
+- Status: `desktop_record_status {"recordingId"?}`; no id lists every registered take (`autoStopped:true` = it hit `maxDurationMs`, call stop to collect it).
+- List: `desktop_record_list` = finished MP4s on disk, newest first.
+- Window mode: give `hwnd` or `titleContains` instead of `monitor` (or call `desktop_record_window_start`): background-capturable, no audio.
+- `audio:false` skips the loopback track; `audioNote` explains an automatically disabled track (no output device, unsupported mix format).
+- `desktop_recorder_open` / `desktop_recorder_close` are retired (errorCode `verb_retired`).
+
+Chrome screen-share recording (the OS picker as consent, system plus mic mixing, WebM, cross-platform) is the puppeteer bridge's `pup_screen_record_*` / `pup_recorder_*`. Both recorders exist on purpose; pick by need.
+
+The sections below predate the native recorder and describe the pup path; treat verb names there as `pup_screen_record_*`.
+
+
+# Adom Bridge: Screen Recording
+
+Adom Bridge (ab) records the whole desktop to a `.webm` file through a
+**visible, consent-gated recorder HUD**. This skill covers that desktop
+recorder. Recording a single browser tab is a different feature owned by the
+Puppeteer bridge (see "Tab recording is NOT this" at the bottom).
+
+## The model: consent by transparency
+
+The recorder is a visible Chrome window in the bottom-right corner of the
+user's screen, always on top. It shows:
+
+- the recording status and a manual Stop button
+- the **reason** you supplied, rendered right in the HUD title
+
+`reason` is REQUIRED on both `desktop_recorder_open` and
+`desktop_record_start`. A recording can never start silently: the user always
+sees that recording is happening and why. The reason is also written to a
+sidecar `.json` next to each clip.
+
+The HUD persists across multiple short clips (a "session"). Only
+`desktop_recorder_close` (or 5 minutes idle) dismisses it.
+
+## Pick the right verb first
+
+| User said | Use |
+|---|---|
+| "record a pup" / "record the tab" / "record this Chrome page" | `pup_record_start` (Puppeteer bridge, tab-scoped, no HUD) |
+| "record my screen" and Hydrogen is available | Hydrogen's built-in `recording start --share screen` |
+| "record everything on screen including KiCad / Fusion / OS dialogs / multiple apps switching" | `desktop_record_start` with `confirmDesktopNotTabRecording: true` |
+| "record a pup tab AND a parallel desktop video at the same time" | Both at once: `pup_record_start` on the tab and `desktop_record_start` on the desktop |
+
+Wrong verb means wrong content: the desktop recorder captures whatever is on
+the monitor at frame time. If the target window is occluded behind the IDE or
+Slack, the clip shows those apps, not the target.
+
+## The guardrail: confirmDesktopNotTabRecording
+
+`desktop_record_start` REQUIRES `confirmDesktopNotTabRecording: true`.
+Without it, the call fails with `errorCode: desktop_record_needs_confirmation`
+and an error string explaining the alternatives (pup_record_start,
+Hydrogen, or pass the confirm). This is intentional friction: acknowledge
+that you understand this captures the WHOLE desktop, not a tab. The confirm
+must be passed on every `desktop_record_start` call, even within one session.
+
+## Verb flow
+
+```bash
+# 1. (Optional) Open the HUD without starting a clip, so the user knows
+#    ahead of time you are about to record.
+adom-bridge desktop_recorder_open '{"reason":"About to record the KiCad export demo"}'
+# -> { "opened": true, "reason": "..." }
+
+# 2. Start a desktop clip. HUD opens if not already open; recording begins.
+adom-bridge desktop_record_start '{
+  "reason":"Parallel desktop angle alongside Hydrogen ralph-loop tab capture",
+  "confirmDesktopNotTabRecording": true,
+  "monitor":"primary",
+  "fps":30,
+  "audio":false
+}'
+# -> { "ok":true, "recordingId":"rec-1", "filePath":"...\\rec-desktop-....webm", ... }
+
+# 3. Drive KiCad / Fusion / whatever you are demoing.
+
+# 4. Stop this clip. The HUD stays open, ready for the next clip.
+adom-bridge desktop_record_stop '{"recordingId":"rec-1"}'
+# -> { "ok":true, "filePath":"...", "sizeKB":4231, "durationMs":18432 }
+
+# 5. Check state at any time.
+adom-bridge desktop_record_status
+# -> { "hudOpen": true, "reason": "...", "currentRecording": ..., "clipsThisSession": ... }
+
+# 6. List completed clips with sidecar metadata (including reason).
+adom-bridge desktop_record_list
+# -> { "recordings": [{recordingId, filePath, sizeKB, durationMs, reason, mtime}] }
+
+# 7. When done: close the HUD (auto-stops any active clip first).
+adom-bridge desktop_recorder_close
+# -> { "ok":true, "sessionSummary":{"clipCount":3, "totalSizeKB":12390, "reason":"...", "clips":[...]} }
+```
+
+### Argument reference (desktop_record_start)
+
+- `reason` (REQUIRED string): why you are recording; renders in the HUD title
+  and the sidecar JSON
+- `confirmDesktopNotTabRecording` (REQUIRED bool): must be `true`, see above
+- `monitor` (optional): `'primary'` | `'all'` | int, default `'primary'`
+- `fps` (optional int, default 30)
+- `audio` (optional bool, default false)
+- `videoBitsPerSecond` (optional int, default 4000000)
+- `maxDurationMs` (optional int, default 600000)
+
+For monitor selection data, `desktop_list_monitors` enumerates all monitors
+with physical and logical bounds, DPI, scale, and the primary flag.
+
+## The user can stop you
+
+The HUD has a manual Stop button. A user click converges through the same
+code path as your `desktop_record_stop` call. Do not fight it: if the user
+stops manually, treat the clip as complete and react accordingly.
+
+## Where files land, and retention
+
+- Each finished clip is a single `.webm` (VP9). The exact on-disk path comes
+  back in `filePath` on start/stop and in `desktop_record_list`.
+- Pull clips to your container with `pull_file`:
+
+```bash
+adom-bridge pull_file '{"filePaths":["C:\\...\\rec-desktop-....webm"], "saveTo":"/tmp"}'
+```
+
+- ab's disk janitor auto-prunes its recordings directory
+  (`%TEMP%\adom-bridge-recordings`) with generous caps: 2 days age,
+  40 files, 3 GB total. Pruning is oldest-first, so the newest files
+  (including an in-progress recording) always survive. Still: pull anything
+  the user wants to keep promptly rather than treating the desktop as
+  long-term storage.
+
+## Tab recording is NOT this
+
+Recording a BROWSER TAB (a pup window, a Chrome page, "record this tab") is
+the Puppeteer bridge's feature: `pup_record_start` / `pup_record_stop`.
+It is tab-scoped, needs no HUD, runs concurrently per tab, and captures the
+tab regardless of OS foreground state. Its documentation ships in the pup
+bridge's own skill; install it with `sync_skills`.

@@ -0,0 +1,148 @@+---+name: adom-bridge-runtimes+description: >+  Managed Node and Python runtimes for Adom Bridge bridges. Use this skill when a+  node or python bridge fails to spawn, when you need to check runtime status with the+  runtimes verb, when a bridge needs Node.js or Python and the box may not have one,+  when npm dependencies for a source-only node bridge are missing, or when you want to+  understand the no-UAC portable node/python install, the prewarm on first launch, the+  Runtimes panel in the GUI, or the loopback-only bind rule for bridge processes.+---++# Managed runtimes: how ab provisions Node and Python for bridges++Adom Bridge owns a global, portable, no-UAC Node and Python that every bridge+shares. A bridge never installs its own interpreter and never pops a UAC or+firewall prompt. Core logic lives in `src-tauri/src/runtime_cache.rs`.++## What the managed runtimes are++Resolution order for `ensure_runtime(app, Node|Python)`, race-safe via a+per-kind install lock (two bridges asking at once never double-download):++1. Already `Ready` in the in-memory state map: return the exe.+2. A **system runtime on PATH** is used as-is (`source: system`), no download.+3. A prior **portable copy** under `~/.adom/adom-runtimes/<kind>-<ver>/`+   (`source: cache`).+4. **Download a portable copy** (Windows): stream-download, extract, atomic+   rename into the runtime dir, emitting `runtime-status` progress events.++Pinned portable versions (one place to bump, in `runtime_cache.rs`):++- Node 22.11.0 (official nodejs.org win-x64 zip)+- Python 3.12.13 (astral-sh python-build-standalone `install_only` tar.gz,+  full CPython with `venv` and `pip`)++The two hard guarantees:++1. **Never a UAC prompt.** The portable runtimes are a zip extract (Node) and+   a tar.gz extract (Python) into `~/.adom/adom-runtimes/`. No MSI, no+   installer, no elevation, no winget.+2. **Never a firewall prompt by default.** ab passes+   `ADOM_BIND_HOST=127.0.0.1` to every bridge process, and bridges must bind+   it. A bare `server.listen(PORT)` binds `0.0.0.0` and triggers the Windows+   Firewall dialog; loopback binds never do.++One known trap the resolver already handles: the Windows Store `python.exe`+app-execution-alias stub (a fake python that prints an install message+instead of a version). `detect_system` accepts a found exe only if it reports+a parseable version; the stub falls through to the portable download.++## The `runtimes` verb (read + on-demand ensure)++```bash+adom-bridge runtimes+# v2.1.14+: kick a provision NOW instead of waiting for a spawn to need it -+# useful before installing an exe-kind bridge whose scripts want Python/Node:+adom-bridge runtimes '{"action":"ensure","runtime":"python"}'+```++Available over the relay and the direct API. Returns a per-runtime snapshot:++- `state`: `absent | installing | ready | failed`+- `source`: `system | cache`+- `version`, plus `pct`/`phase` while a download is in flight++This is the machine-readable "what is installed and at which version" for+cloud AIs. The human-facing mirror is the **Runtimes panel** in the GUI's+Bridges sidebar: a state dot, version, and source per runtime, with live+updates from the `runtime-status` event.++## Prewarm on first launch++`runtime_cache::prewarm_all` fires about 3 seconds after boot on **every**+launch (standalone and embedded), gated by config `prewarm_runtimes`+(default true). It kicks off both `ensure_runtime` calls fire-and-forget:+a system or cached runtime resolves in milliseconds; only a runtime-less box+actually downloads. Turning `prewarm_runtimes` off means runtimes fetch+lazily on the first bridge spawn instead.++Because prewarm is async, a bridge can need Node or Python before it+finishes. The bridge auto-start path calls a non-blocking `runtime_gate`:++- `Ready` -> spawn now (the common case).+- `Warming` -> the verb returns a non-fatal `runtime_warming` result with+  `stillRunning: true` and `statusVerb: "runtimes"`. Poll and retry; this is+  not a failure.+- `Failed` -> a `runtime_failed` result; a retry re-attempts the install.++```bash+# A bridge verb returned runtime_warming? Poll until ready, then retry:+adom-bridge runtimes+# ... wait for state=ready on the needed runtime ...+adom-bridge browser_open_window '{"url": "https://example.com"}'+```++## npm installs for source-only node bridges (`ensure_node_modules`)++A node bridge's wiki zip rightly ships source-only, so its cache dir has no+`node_modules`. At spawn, `ensure_node_modules` resolves dependencies in+this order:++1. The cache dir already has `node_modules`: use it, nothing to do.+2. A **bundled seed** of the same bridge name has `node_modules` AND the+   seed's `bridge.json` version is `>=` the cache version: reuse the seed's+   modules via `NODE_PATH` for the spawn. Instant, no copy, and the seed's+   native bindings are already built for this platform. The version gate is+   the guardrail: a cache strictly newer than the seed may have different+   deps, so stale bundled modules are never reused.+3. Otherwise run `npm install --include=optional` in the cache dir.++npm runs through the **managed runtime's own npm**+(`node <node_modules/npm/bin/npm-cli.js>`), because a portable Node is not+on PATH so a bare `npm` would fail. Bare npm is used only for a system Node.++## When a node or python bridge fails to spawn: what to check++1. **Runtime state first.**+   ```bash+   adom-bridge runtimes+   ```+   - `state: installing`: the portable download is in flight. Poll and retry+     the bridge verb; do not treat `runtime_warming` as an error.+   - `state: failed`: retry the bridge verb (a retry re-attempts the+     install), or check network reachability to nodejs.org / the+     python-build-standalone release host.+   - `state: absent` with `prewarm_runtimes` off: the first bridge spawn+     will fetch lazily; expect a one-time delay.+2. **MODULE_NOT_FOUND from a node bridge** means its dependencies did not+   resolve: verify `ensure_node_modules` ran (cache `node_modules` present,+   or a same-or-newer bundled seed exists), or that the npm install in the+   cache dir succeeded.+3. **A Windows Firewall prompt appeared**: the bridge bound `0.0.0.0`+   instead of honoring `ADOM_BIND_HOST`. That is a bridge bug; bridges must+   bind `process.env.ADOM_BIND_HOST || '127.0.0.1'` (Node) or+   `os.environ.get('ADOM_BIND_HOST', '127.0.0.1')` (Python).+4. **Python shows a strange version or none**: on old ab builds the Windows+   Store python stub could be pinned as a dead system runtime; current+   builds reject it and download the portable Python instead.++## Bridge author contract (summary)++1. Bind `ADOM_BIND_HOST` (loopback), never `0.0.0.0`.+2. Do not bootstrap your own Node or Python. ab provisions the interpreter+   and spawns your entrypoint by absolute path, with no UAC. Shipping a+   source-only node bridge is fine; ab runs npm for you at spawn.++Dev internals and the do-not-regress rules: `skills/MANAGED_RUNTIMES.md`.+Launch-order timeline of every background prewarm task: `skills/PREWARM.md`.

@@ -0,0 +1,159 @@+---+name: adom-bridge-sdk-audit+description: >-+  AUDIT and maintain a shipped bridge: the self-audit checklist to run when asked to 'audit+  against the SDK', how to stay current with SDK changes on your own, the verb-contract quick+  reference, how to get bugs reported in the OUTPUT rather than buried in a skill file, and+  how to file issues against Adom Bridge or the repos you depend on. Use for a periodic health+  check of your bridge or when an SDK-change notice lands on your wiki discussion.+---+++## Self-audit checklist — run this when asked to "audit against the SDK"++When a maintainer says *"audit your code, skills, README, and wiki page against the Bridge SDK,"* **this is the checklist.** Each item names its section below; fix every miss, then re-check.++**⛔ BOUNDARY LINT — run these FIRST; a failure here outranks everything below** *(→ SDK "LINE OF DEMARCATION")*:+- [ ] **ZERO ab-core changes.** Your work touches NO file under `src-tauri/` / `cli/` in the adom-bridge repo. If you have an open PR against ab for a bridge feature, it is wrong by default — the capability belongs in your bridge. `git diff --name-only <base>..HEAD | grep -E '^(src-tauri|cli)/'` must be EMPTY.+- [ ] **No duplicate of a verb ab already ships.** Before writing any desktop capability, list ab's surface (`adom-bridge verbs`, `/verbs`, or the `adom-bridge-verbs` skill) and confirm nothing generic already does it. Window identity, taskbar icon/overlay, jump lists, screenshots, input, files, notifications are **already generic in ab** — call them, don't re-implement them.+- [ ] **ab never learns your app's name.** No `Adom.<YourApp>.` namespace, app-named label, or app-named router baked into ab. Your appId / icon / labels are values YOU pass into ab's generic verbs. `grep -ri "<yourapp>" <path-to-ab>/src-tauri/src/` must be EMPTY.+- [ ] **App-AWARE logic stays in your bridge.** Anything that needs knowledge of how YOUR app behaves — window→session binding, HWND/PID/process-start verification, launch timing, profile layout — is implemented in your bridge and hands ab only a resolved, generic input. If a proposed ab change would require ab to understand your app, it fails the two-part test.+- [ ] **Two-part test on any ab ask:** could an unrelated app use this verb unchanged, AND can ab implement it knowing nothing app-specific? If either is no, build it in the bridge (or ask for a *generic hardening* of an existing verb). **Only once it PASSES does the channel matter: Adom team → send a PR (efficient, welcome); third-party → file a discussion on `adom-bridge`.** Being on the team shortens the path, it does not widen the line — a team PR carrying app-specific code gets the same answer as anyone's.++**KEYWORD + PAGE IDENTITY lint** *(→ SDK "Your bridge's KEYWORD" + Artifact 3)*:+- [ ] **A short user keyword is DECLARED, not just agreed.** One speakable word (`pup`/`kicad`/`pw`), stated in your README's first section ("Say **X** to the AI to reach this bridge"), matching your `bridge.json` `name` AND your verb prefix (`<keyword>_*`) AND your `discovery_triggers`. A keyword that lives only in a conversation does not exist.+- [ ] **Current naming.** The product is **Adom Bridge** (ab). Your page slug, README, and copy use it — a slug or doc still saying `adom-desktop-*` is stale and reads as abandoned. Live bridges are `kicad-bridge`, `fusion-bridge`, `pup-bridge`.+- [ ] **⭐ Your README SHOWS the bridge working — screenshots, not just prose.** `grep -c '!\[' README.md` must be well above zero (pup ships 13, kicad 8, plus demo videos; a brand-new bridge shipped **0**, and its reviewer had no way to see the feature at all). This is the single highest-leverage item on this list: **a reviewer, a user, or John evaluating your PR will NOT build and run your bridge to find out what it does** — especially when doing so would mean running modified core ab. The page is the only window into your work. Capture the actual outcome (the window/app/artifact your verbs produce), and for anything VISUAL — taskbar tiles, jump lists, overlays, rendered output — screenshot it **before and after**, because prose cannot convey it and nobody can verify it otherwise. ab screenshots its own windows (`desktop_screenshot_window` returns a window plus its owned popups), so this is scriptable. Follow the house pattern: kicad's `show-symbol.png` / `show-3d-chip.png` + a demo `.mp4`, fusion's numbered `lib-01…lib-10` walkthrough.+- [ ] **A real 1.6-aspect hero** (~2000x1250) on the page — not the auto-generated OG card, which ab cover-crops and clips. *(→ Card hero)* Open your card in ab and confirm nothing is clipped.+- [ ] **Root `SKILL.md` exists** (not only a `skill-package/` directory) plus the `skills/<name>/SKILL.md` set your pkg ships.+- [ ] **At least one QUALIFIED release** — a real, updater-eligible version with its runtime `.zip`, not exclusively "dev / development candidate / updater-ineligible" rows. A page whose every release is a dev candidate cannot be installed by a normal user.+- [ ] The standard kit is present: `install.sh` / `uninstall.sh`, `CHANGELOG.md`, `PUBLISHING.md`, and the billboard art the other bridges ship.++**bridge.json** (the manifest in your zip):+- [ ] `spawn.kind` ∈ `python|node|exe|external-http`, with **`entrypoint`** (NOT `process`/`cmd`/`args`); `healthEndpoint` is **inside `spawn`**; `port:0` lets ab pick. *(→ bridge.json)*+- [ ] `updateManifestUrl` → YOUR page's manifest (durable auto-update); `docs` → your own page; **`homepage` is a `wiki.adom.inc` URL, NEVER `github.com`.**+- [ ] `detect` declared iff you drive a HOST APP (KiCad/Fusion/Altium…); omitted if you bring your own runtime (pup). `prewarm.assets` declared for heavy downloads (e.g. `chrome-for-testing`). *(→ Cold-start tiers)*+- [ ] **`timeouts`** declared if ANY verb can run longer than 60s (a big export/render/cloud-open) — with a matching **`statusVerb`** to poll. Third-party bridges were 60s-capped before v1.9.79; this is how you raise it. *(→ bridge.json)*++**Artifacts & deps** (the two-artifact split — the #1 inconsistency) *(→ Where every file lives)*:+- [ ] Your Release `.zip` is a **Release asset** (`release upload`), NOT a loose `/files` blob — and old version zips are NOT piling up on `/files` (audit for stray `*-v*.zip`).+- [ ] The **server's** runtime deps live in the **ZIP's** `package.json` (node) / `requirements.txt` (python). The **pkg's** `package.json` declares `dependencies:{"adom/adom-bridge":"^1.9.x"}` (so `pkg install` pulls the ab CLI + core skills) and does NOT list the server's npm deps.+- [ ] A big runtime asset (Mesa, a browser) is a **`prewarm.asset`** or seed-bundled — NOT a loose `/files` blob.+- [ ] Your **manifest** (`adom-bridge-<name>-manifest.json`) is on `/files`; its `url` points at the **Release download**, not at a `/files` blob.+- [ ] **PAYLOAD:** `unzip -l <your zip> | sort -k1 -n -r | head` shows **runtime only** — no `.mp4`/`.png`/`.jpg`/screenshots/CHANGELOG/`.github`. A runtime zip is normally well under 1 MB; if yours is bigger, justify every large entry. `tar tzf <your tgz>` shows **skills only** — zero media, zero binaries. Media belongs on the PAGE. *(→ Payload rules)*+- [ ] **PAGE COPY:** your package `description` AND README each carry the one-sentence statement that `pkg install` installs the bridge's SKILLS for your container, not the bridge runtime. One sentence, not an essay. *(→ Artifact 2)*++**Runtime** (Node/Python bridges) *(→ Runtime contract)*:+- [ ] You bind **`ADOM_BIND_HOST`** (loopback default), never `0.0.0.0`.+- [ ] You do **NOT** bootstrap your own Node/Python — no `winget`/`desktop_install_node`/self-download in code or skills. `spawn.kind` is the declaration; ab provisions it.+- [ ] Release zip is **source-only** (no `node_modules`); you rely on ab's `npm install` (PATH-correct as of v1.9.69) + a lockstep bundled seed for instant spawn. You do NOT put the runtime on PATH yourself.++**Verbs & output** (what the AI actually reads):+- [ ] EVERY verb returns a rich **`_hint`** (+ `_next`/`related`/`pitfalls`). *(→ THE ONE PRINCIPLE)*+- [ ] A `<prefix>_describe` verb lists your whole catalog. *(→ Verb contract)*+- [ ] No verb blocks on a heavy install/download — background it, report `installing`/`warming`; `<prefix>_readiness` is read-only. *(→ Cold-start tiers)*+- [ ] `/health` returns `led`/`summary`/`tooltip` truthfully. *(→ Health + status chip)*+- [ ] **NOT INTERCEPTED: for each of your slowest / most-structured verbs, call YOUR OWN port directly and diff the response key set against the same verb routed through `adom-bridge`.** They must match. If ab's answer is missing fields yours returns (or carries fields you have never implemented), **ab core is answering that verb instead of forwarding it** and your handler never ran. This fails SILENTLY and inverts the blame: nothing errors, the caller gets a plausible well-formed response, and it reads from the outside as "the bridge did not implement the contract." Real case: ab core owned `fusion_start`, so the fusion bridge's `progress`/`startKind`/`timings` never reached callers, on the very verb the measured-progress rule was written for (adom/adom-bridge#86, fixed in ab 2.0.61). Check it after ANY ab upgrade, and file on `adom/adom-bridge` with the two key sets side by side.++  **Run the diff TWICE.** A bridge respawn between the two calls produces a false negative that reads as "my bridge is broken" rather than "ab answered". And note WHY this check has to exist at all: **a swallowed field is indistinguishable from a field you never implemented.** That is precisely why ab's interception of `fusion_start` went unnoticed for so long - the absence looked like the bridge's own gap, so nobody went looking on ab's side.++**Discovery** (can a plain request find you?):+- [ ] **10+ user-task `discovery_triggers`** (everyday phrasings, NOT dev jargon). **No triggers = invisible.** *(→ Artifact 3)*+- [ ] You ran `discover preview --json` on 5-7 real user queries and land **top-3** for each.+- [ ] Triggers stay in YOUR niche — you don't poach a sibling's (login/forms → native-browser, not pup). `discovery_pitch` is an INSTRUCTION.++**Skills & docs** (what the container + humans read):+- [ ] Your pkg ships **ONLY your USER skill(s)** — a real `skills/<name>/SKILL.md` (core user skill + user sub-skills) with a `Parent skill:` first body line; every path listed EXPLICITLY (no globs) in `files[]` + install.sh/uninstall.sh. *(→ Artifact 2 + The SKILL SET)*+- [ ] **DEV + PUBLISH skills are in your source REPO, NOT the pkg** — not in `files[]`, not scoped in via `user-invocable:false`. A developer gets them by cloning the source; the normal user never needs them. Open-vs-closed source is irrelevant (it only sets repo visibility). *(→ Where every file lives)*+- [ ] Your pkg's `package.json` declares `dependencies:{"adom/adom-bridge":"^1.9.x"}` so `pkg install` pulls the ab CLI + core skills the container needs. *(→ Where every file lives)*+- [ ] Your USER skill leads with the cold-start "read before you panic" section + the 8 conventions, and points the AI at `bridge_readiness`. *(→ USER-skill conventions)*+- [ ] README + wiki page + skills all AGREE with the above (no stale github links, no wrong schema, triggers vetted).++---++## Staying current — catch up on SDK changes yourself (no prompt needed)++This SDK evolves. When it does, ab posts a re-audit notice to **YOUR bridge's wiki discussion** and re-publishes this billboard. You do NOT need a human to hand you a prompt — self-serve at the start of a work session:++1. **Check your discussion for a notice.** `adom-wiki discussion list <your-slug>` (or open your page's Discussions tab) and read any "SDK update" / "re-audit" thread. A notice can be EDITED after posting (a correction), so always read the **current** body, not a cached earlier version.+2. **Re-read this billboard**, especially "Where every file lives" (above) and the "Self-audit checklist" (below): `https://wiki.adom.inc/adom/adom-bridge` (or `curl -s https://wiki.adom.inc/api/v1/pages/adom-bridge-sdk/files/README.md`).+3. **Run the Self-audit checklist** (next section) against your code, `bridge.json`, skills, README, and wiki page. Fix every miss.+4. **Reply on the discussion** with what you changed or any blockers. That thread is the ONLY channel ab uses to reach you, so closing the loop there is how ab knows you are current.++---++## Verb contract (quick reference)++- **Naming:** every verb is `<name>_<verb>` (`blender_render`, `blender_status`). ab routes any verb with your prefix to you.+- **Request:** ab POSTs `{ "command":"<verb>", "args":{…} }` to your port. **Response:** JSON with at least `success` (bool); human/AI output in `output`, errors in `error` (+ an `errorCode` for machine-actionable failures). ab relays everything else verbatim — so ALWAYS add `_hint`/`_next`/`related`/`pitfalls`.+- **Long-running verbs:** return promptly with a job id + set `statusVerb`; the caller polls instead of blocking. On a timeout ab auto-returns `{stillRunning:true, statusVerb, timeoutSeconds}`. If a verb genuinely blocks past 60s (a synchronous export/render), **also declare a `timeouts` block** (v1.9.79) so ab's HTTP budget matches — otherwise ab cuts the connection at 60s (third-party bridges were hard-capped there before v1.9.79).+- **`<prefix>describe`:** return your full verb catalog (`{verbs:[{name,summary,input,output,timeoutSeconds,statusVerb,longRunning,example,hint,related,pitfalls}]}`). ab caches it (`~/.adom/bridge-verbs/<name>.json`) and shows it in the GUI Verbs tab — but remember, `describe` is read rarely; the per-call hints are what carry the AI.+- **Keyboard input: route through ab's `desktop_press_key` — do NOT reimplement chords.** ab's key verb already does full modifier chords (`"shift+s"`, `"ctrl+shift+p"`, `"alt+f4"` — modifiers held via SendInput, key tapped, modifiers released in reverse), foregrounds the target window first (`{window|titleContains|hwnd}`) so CEF/Qt apps like Fusion receive it, and every bridge inherits it via the `/command` desktop passthrough (`{"command":"press_key", ...}` on the desktop namespace). A bridge-local `*_send_key` that parses only single keys (the Fusion bridge's `fusion_send_key` circa v1.6.x — `"shift+s"` → "Unknown key") duplicates ab's work and drifts; keep such a verb only for SendMessage-to-exact-hwnd cases ab's focus-first model can't cover, and say so in its `describe`.+- **Host-app-optional verbs (v1.9.76):** declare `detect.hostAppOptionalVerbs` (bare names, e.g. `["readiness","describe"]`) in `bridge.json` so ab forwards those verbs to your running bridge even when your host app is absent — ab's built-in read-only set {readiness, describe, get_app_state, status} is always forwarded. And declare **`detect.installVerb`** (e.g. `"kicad_upgrade"`) so `bridge_readiness` recommends YOUR installer over the generic winget fallback.++## Ask the AI to report bugs, in the OUTPUT, not the skill file++You cannot reproduce every environment. Your bridge runs on machines with browser installs, OS versions, security policies, hardware and concurrency patterns you will never have locally. **The AI driving your bridge is standing on exactly that machine.** It is the only party holding the failing response, and the moment it holds it is the only moment it will file anything.++So make the invitation part of your verb output, the same way `_hint` is. This is THE ONE PRINCIPLE at the top of this page applied to feedback: the AI almost never reads your on-disk SKILL.md, and it ALWAYS reads the output of a CLI call.++**The evidence that this channel works.** In roughly two days, wiki issues filed against the puppeteer bridge produced: a CPU-pegging orphaned-renderer bug that froze a laptop and forced a reboot (#14, #21), a respawn failure that broke the bridge on every idle cycle (#15), a session-tracking bug where windows were open and drivable but reported as zero (#16), a repo-versus-release divergence that would have silently reverted five releases (#19), and a concurrency and readiness report that caught a live blocking regression shipped hours earlier (#22). **Not one of those would have been found on a maintainer's machine.** They came from real installs: different Chrome and Edge combinations, different ab versions, concurrent agents, a macOS box, a stalled download.++**Return a `_reportIssues` field naming YOUR page's issue list, with the exact commands:**++```jsonc+{+  "success": false,+  "errorCode": "…",+  "_hint": "…",+  "_reportIssues": "THIS MAY BE A <BRIDGE> BUG. PLEASE REPORT IT. Check for a duplicate with `adom-wiki issue list adom/<your-slug>`, then file: `adom-wiki issue create adom/<your-slug> --title \"<one-line symptom>\" --category bug-report --body \"<what you ran, what you expected, what happened, the VERBATIM response JSON, the bridge version from bridge_list, and the OS>\"`. Reports from real machines are the only way this bridge gets correct. (An ab-core problem, such as the relay, bridge lifecycle or caller identity, belongs on adom/adom-bridge instead.)"+}+```++**When to attach it. Throttle it, or the AI learns to skip it:**++| Moment | Why |+|---|---|+| **Always on a failure** | The highest-value moment: a bug just happened and the evidence is still in the response. |+| **Once per bridge process, on the first verb** | Orientation, so the AI knows where to report *before* anything breaks. |+| **Occasionally after that** (e.g. every ~40th call) | A quiet reminder on a long-running session without taxing every response. |++A line on **every** response is noise that trains the caller to ignore the field. A line on every **failure** is a bug report waiting to be filed.++**Make it actionable, not a slogan.** "Report bugs" produces nothing. Give the AI the exact `adom-wiki issue create` command, your slug, a `--category`, and the list of evidence to include (the verbatim response JSON and your bridge version are the two that make a report reproducible). Tell it to check for a duplicate first: an `issue list` call costs nothing and keeps your page clean.++**Route the report to the repo that owns the code.** Say explicitly, in the same string, that ab-core problems (the relay and `/command` passthrough, spawn and provisioning, bridge lifecycle, caller identity) go to **`adom/adom-bridge`**, not to your page. Authors get this wrong in the other direction too, which is the next section: a misfiled issue is a note to yourself that the people who can fix it never read.++**Let the user turn it off.** Ship a settings toggle (pup uses `pup_configure {reportIssues:"off"}`) so a user who finds it noisy can silence it without losing functionality. Default it **on**: the cost is a few tokens on failures, and the benefit is the bug class you would otherwise ship to every user.++**Reference implementation:** the puppeteer bridge does this at its single `sendJSON` chokepoint (v1.9.95), so all ~155 response sites are covered from one place, and it never overwrites a `_hint` a handler already set.++---++## Filing issues against ab (and the other repos you depend on)++You WILL find ab-core bugs and gaps while building your bridge. That is expected and useful. But file them in the RIGHT repo's issue list, or the people who can fix them never see it.++**The rule: an issue lives on the issue list of the repo that OWNS the code that must change.**++- A bug in YOUR bridge's verb / hint / self-heal / status chip goes to **YOUR page's issue list** (or you just fix it, since you own it).+- A missing or broken **ab-CORE** capability (a lifecycle verb, a spawn / provision / bind behavior, the relay passthrough dropping a field, a manifest field ab must honor, the status-chip contract) goes to **`adom/adom-bridge`**, NOT your own page. ab-core's maintainers and AI watch `adom/adom-bridge`; they do NOT read your bridge page's issues. **An ab ask filed on your own page is a note to yourself.**+- A **wiki or CLI** bug goes to `adom/wiki`. A **sibling bridge's** bug goes to that bridge's page.++**How (the CLI):**++```bash+adom-wiki issue list   adom/adom-bridge            # FIRST: skim for a dup, comment if one exists+adom-wiki issue create adom/adom-bridge \+  --title "<verb or subsystem>: <the gap in one line>" \+  --category bug-report \+  --body "$(cat your-writeup.md)"+```++**Write the body like a good bug report:** what you hit live (with the date and the ab version), the measured behavior, the ab-owned root cause if you found one, and a concrete ask. Separate clearly what is ab-core's to fix from what is yours, and say so explicitly, so the two are never conflated.++**After you file:** the ab-core thread replies on that issue. Read the reply, it may change your plan (for example "fixed in ab X.Y, bump your pin"). That issue thread is the cross-repo channel; keep the loop closed there.++**Why this matters most for ab:** ab-core spawns you, provisions your runtime, relays your verbs, and installs you, so ab is the repo you will file against most often. Get the destination right the first time. The established precedent all sits on `adom/adom-bridge`: #26 and #27 (pup to ab, Chrome for Testing), #16 (pup to ab, window-verb interception), #3 / #20 / #21 (Bridge SDK asks).++---

@@ -0,0 +1,328 @@+---+name: adom-bridge-sdk-callback+description: >-+  Call Adom Bridge BACK from inside your bridge: the loopback direct API gives you the FULL ab+  verb set (screenshots, files, windows, notifications, other bridges), how to forward caller+  provenance so the user sees WHICH AI thread asked (X-Adom-Caller-* headers and the+  delegation chain), and how to brand a window you borrowed (window identity, taskbar tile,+  jump list, overlay badge). Use when your bridge needs an ab verb, when the Activity Log or+  an approval prompt misattributes your calls, or when a window you drive presents as the+  wrong app.+---+++## Calling ab back (outbound) — you reach the FULL ab verb set (v1.9.84)++Your callback channel is ab's loopback direct API: `POST <ADOM_DIRECT_API_URL>/command` (env var; fallback `~/.adom/direct-api-port` = `host:port`). As of **ab v1.9.84** this reaches **every dispatchable ab verb**, not just `desktop_*` — same dispatcher the CLI uses, identical JSON back. `GET <ADOM_DIRECT_API_URL>/commands` lists the full set so you can capability-probe (don't hardcode).++- **`app` is OPTIONAL** — inferred from the command. Just `POST {"command":"<verb>","args":{…}}`. (Pass `app` to override the inference.)+- **Top-level verbs you can now call:** `notify_user` (walk the user through something — returns `{action:"displayed"}`), `notify_response` (poll a toast button/input), `targets` (list the OTHER ABs on the relay), `ping`, `bridge_list`, `runtimes`, `status`, … — plus every `desktop_*` and every *other* bridge's verbs.+- **Cross-ab (`target`):** add `"target":"<clientName>"` (from `targets`) or `"all"` to route the call to a PEER ab via the relay — e.g. **you run on a VM but the user is on their laptop**: `notify_user` with `target:"<laptop clientName>"` reaches them where they are. `"attended"` isn't resolvable yet (use a concrete clientName).+- **`X-Adom-Bridge-Token` (optional attribution + identity migration).** ab injects `ADOM_BRIDGE_TOKEN` into your spawn env. Send it as the `X-Adom-Bridge-Token` header and ab badges your calls "bridge" in its Activity Log and applies the temporary bridge exemption from `caller_identity_required`. It is **NOT** an approval gate: you're trusted by transport (ab binds 127.0.0.1 only + the user consented by installing you), so your calls — including `write_file`/`run_script` — run ungated. A stale token is warned once and treated as omitted: an identified callback continues under the `direct:<port>` badge; an unidentified one receives the normal identity teaching refusal. Always forward the caller headers below or send your own explicit `caller.aiThread`.+- **`cliRequired`** verbs (`pull_file`/`send_files`/`shell_execute`) return `412 cli_required` — they need the streaming/approval CLI path, not this HTTP channel.++```bash+# Discover, then call — no hardcoding.+curl -s "$ADOM_DIRECT_API_URL/commands"+curl -s -X POST "$ADOM_DIRECT_API_URL/command" -H 'Content-Type: application/json' \+  -H "X-Adom-Bridge-Token: $ADOM_BRIDGE_TOKEN" \+  -d '{"command":"notify_user","args":{"title":"Heads up","body":"…"}}'+```++### Notify the user AND get their answer back (`notify_user` — two separate axes)++Your bridge can prompt the user with a native toast and read their reply — the same `notify_user` verb the AI uses. It has **two independent axes; don't conflate them** (full ref: the `adom-bridge-notify` skill / `skills/NOTIFY.md`):++- **Axis 1 — get the answer back.** There is no server-push, so either **`wait:true`** (the `notify_user` call blocks and returns the user's choice inline — best for a one-shot prompt) or fire-and-continue then poll **`notify_events {sinceSeq}`** (drains every click) / **`notify_response {id}`**. The click is recorded durably, so it survives even on a headless box.+- **Axis 2 — reveal a window (`focus`).** A LOCAL desktop action, not a reply. `focus:{hwnd|cacheKey|titleContains|app|host}` raises a window on the user's screen when they click. **`focus:{app:"<your-exe>"}`** points the click at a window YOUR bridge drives; **`focus:{host:true}`** points it at the app ab is embedded under (Hydrogen). Pass `focus` whenever the toast is *about* a window, so the click lands there instead of opening ab.++```bash+# Ask, and get the answer back inline:+curl -s -X POST "$ADOM_DIRECT_API_URL/command" -H "X-Adom-Bridge-Token: $ADOM_BRIDGE_TOKEN" \+  -d '{"command":"notify_user","args":{"title":"Overwrite board?","scenario":"reminder",+       "buttons":[{"label":"Overwrite"},{"label":"Cancel"}],"wait":true,"timeoutSec":90}}'+#   -> { "pending": false, "action": "Overwrite" }+```++The response always carries `_capabilities` / `_couldHaveDoneBetter` when a call left something on the table — read them; they teach the verb from use.++## Reply shapes you will parse (wiki #121 — VALIDATE against these, don't guess)++The altium bridge's dialog reaper was blind for six releases because it parsed+`desktop_find_controls` under a key ab never uses. These are the shapes that+have burned real bridges; validate your parsing against them at build time:++| Verb | The keys that matter | The trap |+|---|---|---|+| `desktop_find_controls` | matches under **`matches`** (array), best match first | it is NOT `controls` — parsing `controls` silently yields zero forever |+| `desktop_screenshot_window` | **two envelope forms**: a file capture carries top-level `fullPath`/`safePath` (+ CLI-side `savedTo` after auto-pull); a base64-only capture (direct API with no pull) carries `data.image` | check for BOTH; do not assume one. `coordMap.shotId` + top-level `shotId` are on the direct-API response — use `{space:"image", shotId, x, y}` for zero-math clicks. `screenshots[]` holds owned-popup children, each with its own shotId |+| `pup_screenshot` via the CLI | the local-save envelope is MERGED OVER the bridge's response (v2.1.10) | bridge-added keys (e.g. `capturedVia`) survive; `base64` is stripped after the local save |+| `desktop_list_windows` | rows carry `hwnd, title, className, kind, z, rect{}` + (v2.1.12) `owner, pid, image, minimized, maximized, enabled, hung` | ZERO rows with `degraded:true` = the enumeration could NOT answer (wedged/locked session) — never read it as "no windows" |+| `desktop_enum_windows` | same degraded rule for an UNFILTERED call | a FILTERED empty result is a legitimate no-match and is not flagged |+| `desktop_wait_for_window` | `{appeared, waitedMs, window?}` — `appeared` means "the requested condition was met", including `state:"absent"` | with `state:"absent"`, `appeared:true` means the window is GONE |+| every bridge-routed verb | `timeoutSeconds` + (on timeout) `stillRunning:true` + `statusVerb` | a timeout is NON-terminal: poll `statusVerb`, do not blindly re-issue |++Compatibility rule ab holds itself to: reply keys never silently rename — a+renamed key keeps the old name as an alias for a major version. If you find a+shape mismatch between this table and a live response, that is a bug — file it+on `adom/adom-bridge`.++### The machine-readable contract (v2.1.51, wiki #121)++The table above is prose. Two things make it checkable:++1. **Every reply carries `schemaVersion`** (an integer, stamped by ab core on+   every path). It bumps only on a rename, removal or type change of a+   documented key; additive keys never bump it. Compare it to the catalog you+   validated against and re-fetch the catalog when it changes.+2. **`desktop_reply_schema {verb?}`** returns the envelope (the two forms, the+   universal keys, the rules) and per-verb JSON-Schema fragments+   (`shape.properties` / `shape.required` / `since` / `notes`) for the ab-core+   verbs bridges parse in safety paths: list_windows, find_window,+   screenshot_window/screen, bring_to_front, set_window_state,+   find_control(s), ui_from_point, ui_tree, ui_text, the input verbs, the+   recorder, app_instances. `covered` lists them; an uncovered verb answers+   `coveredVerb:false` with the envelope only, never a guess.++**The two envelope forms** are the trap behind "three different shapes":++| Form | Looks like | Where the verb's data is |+|---|---|---|+| A `command_result` | `{success, output, error}` (+ promoted keys such as `fullPath`) | `output` is a **JSON-encoded string**: `JSON.parse(output).data` (a few verbs, e.g. `desktop_find_window`, decode to a flat object with no `data`) |+| B flat | `{success, ...verb keys}` | top level |++**Strict parsing, the SDK way.** Fetch the catalog once at build/startup and+make a missing required key an error in any safety path:++```python+import json, subprocess++def catalog(verb):+    out = subprocess.run(["adom-bridge", "desktop_reply_schema", json.dumps({"verb": verb})],+                         capture_output=True, text=True).stdout+    c = json.loads(out)+    if not c.get("coveredVerb"):+        raise RuntimeError(f"{verb} has no published shape; do not parse it in a safety path")+    return c["schemaVersion"], c["entry"]++SCHEMA_VERSION, FIND_CONTROLS = catalog("desktop_find_controls")++def strict(reply, entry, verb):+    if reply.get("schemaVersion") != SCHEMA_VERSION:+        raise RuntimeError(f"{verb}: schemaVersion {reply.get('schemaVersion')} != {SCHEMA_VERSION}; re-fetch the catalog")+    body = reply+    if entry["form"] == "A":+        body = json.loads(reply["output"])+    missing = [k for k in entry["shape"]["required"] if k not in body]+    if reply.get("success") and missing:+        raise RuntimeError(f"{verb}: reply is missing documented keys {missing}")+    return body++body = strict(ab("desktop_find_controls", {...}), FIND_CONTROLS, "desktop_find_controls")+buttons = body["matches"]   # KeyError here is a real bug, not an empty dialog+```++The point is the last line: the altium reaper defaulted `controls` to `[]` and+sat blind for six releases. With the catalog, that is a crash on the first+run, which is what you want in a reaper.++---++## Caller provenance: WHO asked (v1.9.180)++A user runs roughly **20 AI threads against one desktop**. Until v1.9.180 ab relayed every command indistinguishably, so a bridge received **no caller identity at all**. Three consequences, all real:++- You could not **arbitrate concurrent agents** — two threads grabbing the same session looked identical to you.+- No bridge log could **attribute a verb** to the thread that issued it, so interference was impossible to reconstruct afterwards.+- Any agent's `bridge_kill` **destroyed every other agent's work**, silently, with no way for anyone to see who did it.++Filed as wiki issue `adom/adom-bridge#34` by AdityaAngajala, with the pup half at `adom/pup-bridge#22`.++### What you now receive, for free++ab stamps three headers on **every relayed bridge request** — all four request paths (browser, kicad, fusion, and the dynamic third-party dispatch):++| Header | What it carries |+|---|---|+| `X-Adom-Caller-Thread` | The AI thread / conversation tab name, self-reported by the caller |+| `X-Adom-Caller-Container` | The container it runs in |+| `X-Adom-Caller-Reason` | The per-call justification, when the caller supplied one (control chars stripped, truncated to 300 chars) |+| `X-Adom-Verified-Origin` | **v2.0.96+ (wiki #114): ab-VERIFIED transport origin — the ONE header you may gate on.** `relay` (arrived over the cloud-AI relay websocket), `local` (loopback direct API: local CLI, ah, a local agent), or `bridge` (a bridge callback carrying a valid spawn token). ab authors this header itself from the connection it actually observed; a caller cannot supply or override it. |++**You do nothing to receive these.** No manifest field, no signature change, no opt-in. Reading them is the opt-in part.++### Trust rule — read this before you use them for anything++These values are **SELF-ASSERTED**, exactly like `reason`. Use them for **attribution, logging, UX and arbitration hints**. **NEVER for authorization, and never as a security boundary.**++ab's own security model is transport-based (the `adom-bridge-permissions` skill has the full model): a caller is trusted because of *how it reached ab*, not because of what it *says about itself*. A header a caller supplies about itself cannot gate anything — if you write `if (thread === "admin-tab") allowDangerousThing()`, you have written a hole, not a check.++One asymmetry worth knowing: the container name in `X-Adom-Caller-Container` is the one the **caller claimed**. ab separately knows a **verified** container (the authenticated relay connection name) and shows the user **both** when they disagree. You only get the claimed one, so treat it as a label, not an identity.++**The exception is `X-Adom-Verified-Origin` (v2.0.96+): that one IS a security signal.** A local-only verb (a credential reveal, a vault unlock) refuses when it reads `relay` — honestly, because ab stamped the value from the transport it observed, not from anything the caller said. Two caveats before you build a gate on it:++1. **It describes the LAST hop into ab.** A bridge callback made on behalf of a relayed AI thread arrives as `bridge`, not `relay` — the relayed identity rides only in the (self-reported) `X-Adom-Caller-Delegate` chain. So a local-only gate should refuse `relay`, decide its own policy for `bridge` (refuse, or require the delegate chain to be empty), and accept `local`.+2. **It authenticates the ab-to-you hop only.** Your HTTP port is loopback, so anything else that reaches it directly is by definition a local process — `local` remains true for those, but they carry no header at all. Treat a MISSING header as `local` from an unidentified local caller (or refuse, if your verb warrants it); never treat it as `relay`-safe.++### What to do with it++**1. Log it.** Put the thread in your per-verb log line. This is the single highest-value use, and it is three lines of code:++```javascript+// node — read once, at the top of your request handler+const caller = {+  thread:    req.headers['x-adom-caller-thread']    || 'unidentified',+  container: req.headers['x-adom-caller-container'] || 'unknown',+  reason:    req.headers['x-adom-caller-reason']    || null,+};+console.log(`[verb] ${verb} session=${sessionId} caller="${caller.thread}"`);+```++```python+# python — same idea; header lookup is case-insensitive on BaseHTTPRequestHandler+caller_thread    = self.headers.get('X-Adom-Caller-Thread', 'unidentified')+caller_container = self.headers.get('X-Adom-Caller-Container', 'unknown')+caller_reason    = self.headers.get('X-Adom-Caller-Reason')+log.info('[verb] %s session=%s caller="%s"', verb, session_id, caller_thread)+```++That one field is what makes an interference report reconstructable: `[verb] pup_eval session=rev caller="chip-fetcher tab 3"` answers "who moved my page?" instantly, where a bare `[verb] pup_eval session=rev` never can.++**2. Arbitrate.** If your bridge has **sessions or resources an agent can own** — pup sessions are the motivating case — record the owning thread at creation time and check it on every later use:++```javascript+// on create+sessions.set(id, { ...state, ownerThread: caller.thread });++// on use by a DIFFERENT thread+const s = sessions.get(id);+if (s.ownerThread && s.ownerThread !== caller.thread) {+  // warn loudly by default; refuse only if this is destructive+  result._warning =+    `session ${id} is owned by "${s.ownerThread}" — you are "${caller.thread}". ` ++    `Two agents driving one session will interfere. Coordinate, or open your own session.`;+}+```++The recommended posture:++- **Warn loudly by default.** A second agent reading or screenshotting a session is usually fine, and hard-blocking it turns a shared machine into a locked one.+- **Refuse only for destructive operations** — closing, resetting, navigating away, deleting.+- **Always name the current owner in the message.** The whole point is that the second agent can now go coordinate with a thread it can identify. An error that says "session busy" without a name is barely better than no header at all.++**3. Label the UI.** If your bridge drives a visible window, put the owning thread where the **user** can see it — window title, taskbar tooltip, or jump-list name — via `desktop_set_window_identity` (and `desktop_taskbar`'s `thumbnailTooltip` for uncapped hover text). The user is the one with 20 tabs open; showing which tab owns which window is the fix for their side of the problem. Full guide: the `adom-bridge-window-identity` skill, and the "Branding + driving a window you borrowed" section immediately below.++**4. Report it back.** Include the owning thread in your **status / list verbs**, so an agent can *discover* it is not alone before it stomps on something:++```jsonc+// <prefix>_list_sessions+{ "sessions": [ { "id": "rev", "ownerThread": "chip-fetcher tab 3", "url": "…" } ],+  "_hint": "A session with an ownerThread other than yours is being driven by another AI thread. Open your own session rather than sharing one." }+```++### Notifications already carry it++`notify_user` derives its toast attribution line from the caller automatically, so a toast your bridge sends **on an agent's behalf already names the thread** — you do not have to build that string. Pass an explicit `attribution` string only when you want to override it.++### ⚠ REQUIRED — when YOU call an ab verb, forward the identity++This is the half most bridges will miss, and it is the half that makes the whole feature work or fail.++Your bridge calls ab verbs to do its job: `desktop_screenshot_window`, `desktop_set_window_identity`, `notify_user`, `desktop_taskbar`. When you make that call **while carrying out a verb an AI thread asked you for, you are acting on that thread's behalf** — so echo the identity you were handed straight back onto your own request. Otherwise the chain dies at your doorstep: the user's Activity Log says *"pup did this"*, the originating thread vanishes, and the approval toast asks them to authorize a nameless bridge.++**Echo all four headers, verbatim:**++```javascript+// node — inside the handler for a verb an AI asked you for+const fwd = {+  'X-Adom-Caller-Thread':    req.headers['x-adom-caller-thread']    || '',+  'X-Adom-Caller-Container': req.headers['x-adom-caller-container'] || '',+  'X-Adom-Caller-Reason':    req.headers['x-adom-caller-reason']    || '',+  'X-Adom-Caller-Delegate':  'pup',   // ← YOUR bridge name+};+await fetch(`http://127.0.0.1:${adPort}/command`, {+  method: 'POST',+  headers: { 'Content-Type': 'application/json', ...fwd },+  body: JSON.stringify({ command: 'desktop_screenshot_window', args: { hwnd } }),+});+```++```python+fwd = {+    'X-Adom-Caller-Thread':    self.headers.get('X-Adom-Caller-Thread', ''),+    'X-Adom-Caller-Container': self.headers.get('X-Adom-Caller-Container', ''),+    'X-Adom-Caller-Reason':    self.headers.get('X-Adom-Caller-Reason', ''),+    'X-Adom-Caller-Delegate':  'kicad',   # YOUR bridge name+}+```++`X-Adom-Caller-Delegate` is the one you **add** rather than forward. It names *you*, and it is what lets ab show the user both facts at once: **`chip-fetcher tab 3 (via pup)`**. Attributing the call to the thread alone would hide who ran it; attributing it to the bridge alone would hide who asked. Omit the header and ab falls back to the generic `via bridge`, which is honest but much less useful.++**When you are acting on your OWN behalf — a health poll, a timer, a crash cleanup — do NOT forward a stale identity.** Send your own instead:++```jsonc+{ "command": "notify_user",+  "args": { "caller": { "aiThread": "pup bridge (self)", "containerName": "local" }, … } }+```++An explicit `caller` block in the args always beats the headers, so this is unambiguous.++**Two things ab does for you here:** explicit args win over forwarded headers (so the override above just works), and ab carries the delegate forward onto any onward hop, so a chain two bridges deep still shows the original delegate.++### Where it comes from (the caller side)++Useful to understand, though none of it is your responsibility:++```bash+# Per call — the CORRECT mechanism:+adom-bridge --ai-thread "chip-fetcher tab 3" <verb> '<json>'+```++The `adom-bridge` CLI attaches a `caller` block to **every** verb automatically. A relay call with **no `aiThread` is REFUSED by ab** with `errorCode: caller_identity_required` before it ever reaches a bridge.++> **Correction, 2026-07-25 (ab 1.9.182):** an earlier version of this page told callers to `export ADOM_AI_THREAD` once per session. **That advice was wrong and has been withdrawn.** Roughly 20 AI threads share one container and one `$HOME`, so the env var scopes to the shell environment, not to the thread — every thread then reports the *same* name, which is worse than no name at all because it is confident and plausible. It also failed silently: tool shells are non-interactive, so an export appended below `~/.bashrc`'s `case $- in *i*` early-return never ran. The env var is still honored, but only fits a container running exactly one agent (CI, a single-purpose job). **If your bridge's own docs repeat the export advice, please correct them.**++**So by the time a request reaches you, identity is normally present.** Relay callers and ordinary loopback direct-command callers—including Hydrogen, the local CLI, and an adopted bridge with an omitted or stale spawn token—are required to identify. A bridge carrying the current core process's spawn token retains a temporary migration exemption; top-level discovery/status endpoints may also bypass the command identity chokepoint. Code for the absent case (`|| 'unidentified'`) and never assume the header exists.++### If your bridge wants to REQUIRE identity — use the shared contract++Some verbs are worth refusing anonymously. If you do, **use ab's exact refusal shape** so the AI sees one consistent remedy across the whole ecosystem instead of a different fix per bridge:++```jsonc+{ "success": false, "errorCode": "caller_identity_required",+  "error": "'<verb>' needs to know WHO is asking — the user runs many AI threads and needs to see which one drove this.",+  "supplyIdentity": {+    "bestWay": "adom-bridge --ai-thread \"<your conversation name>\" <verb> '<json>'",+    "orInArgs": { "caller": { "aiThread": "<name>", "containerName": "<container>" } }+  },+  "_hint": "This is attribution, not a permission check — the name is self-reported and nothing is gated on it." }+```++Reusing `caller_identity_required` verbatim is the point: an AI that learned the remedy once applies it everywhere.++### Self-audit++- [ ] Does every verb log line include the **caller thread**?+- [ ] Do your **session-creating** verbs record the owning thread on the session?+- [ ] Do your **session-using** verbs warn (or, if destructive, refuse) when a different thread arrives — **naming the current owner**?+- [ ] Does any **window you drive** show the owning thread to the user (title / tooltip / jump-list)?+- [ ] Do your **status / list verbs** report `ownerThread` so an agent can discover it is not alone?+- [ ] **When you call an ab verb on a thread's behalf, do you FORWARD all three caller headers plus your own `X-Adom-Caller-Delegate`?**+- [ ] When you call an ab verb on your **own** behalf (poll, timer, cleanup), do you send your own `caller` block rather than a stale forwarded one?+- [ ] If your docs told callers to `export ADOM_AI_THREAD`, have you corrected them to the per-call `--ai-thread` flag?+- [ ] Have you confirmed you use these headers **nowhere** as an authorization check?++---++## Branding + driving a window you borrowed (window identity + taskbar, v1.9.106–1.9.153)++If your bridge drives a window another process owns — the classic case is a **Chrome for Testing** window that otherwise reads *"Test"* with Chrome's icon — ab gives you a generic verb family to make it present as YOUR app across every Windows shell surface, and to show live status on its taskbar button. ab stays generic: it applies whatever name/icon/command you pass; it knows nothing about your app. **Full guide: the `adom-bridge-window-identity` skill** (`https://wiki.adom.inc/api/v1/pages/adom-bridge/files/docs/WINDOW_IDENTITY.md` or the repo `skills/WINDOW_IDENTITY.md`). The essentials:++- **Two halves, you need both:** `desktop_register_app_identity {appId, displayName, iconPath, shortcut}` teaches Windows what an AUMID means (HKCU only, no UAC; `shortcut:false` for a per-session id with no Start Menu spam), and `desktop_set_window_identity {hwnd, appId, iconPath, displayName, relaunchCommand}` stamps it on the live window. Stamp without register → Alt-Tab / taskbar fall back to the owning exe's icon.+- **Per-session identity:** register `shortcut:false` per window (e.g. `Adom.Pup.<sessionId>`) so each keeps its own taskbar button; `desktop_unregister_app_identity {appId}` on close. Known cost (wiki #155, measured): a registry-only identity's taskbar jump list flashes on the FIRST right-click and stays on the second, because the shell resolves a shortcut-less AUMID lazily. `anchor:true` fixes it by dropping a small visible anchor `.lnk` into one Start Menu subfolder (`anchorFolder`, default "Adom Bridge"; pass the same value on unregister), but that IS a Start Menu entry (All apps, "Recently added", search; a hidden `.lnk`, `NoStartPage` or `SHAddToRecentDocs` do not anchor), so the default is OFF: a clean Start Menu over a first-click flyout. Opt in only when the user prefers the flyout.+- **Jump list + header:** `desktop_set_window_jumplist {appId, tasks, hwnd?, headerIcon?, headerCommand?}` adds the right-click menu AND (with `hwnd`+`headerIcon`) brands the header row (the app tile above Pin/Close) with no Start Menu shortcut.+- **Taskbar status:** `desktop_taskbar {hwnd, progress?, overlay?, flash?, thumbnailTooltip?, thumbnailClip?}` paints glanceable state on any window's button. **New in v1.9.153:** `thumbnailTooltip` is the ONLY uncapped hover-text surface (the window title truncates ~25-30 chars; this does not, and takes newlines; `""` clears it), and `thumbnailClip:{x,y,w,h}` crops the live hover preview to a region (`null` resets). Overlay compositing (`overlay.avatar`/`profileDir`) preserves a browser profile face while adding your mark.+- **Icon format — read the `iconCheck` in every response.** The identity verbs inspect any icon you pass and return `iconCheck {kind,sizes,issues,ok,hint}`. The traps it catches: a **256px `.ico` size that is not PNG-compressed** renders as the generic white-document icon (Vista+ rule); **SVG can't be loaded** by the Win32 shell; the AUMID registry icon wants a `.ico`/`.png`, not an `.exe`. If `iconCheck.ok` is false, fix the file and re-stamp — don't ship the broken icon. Ship a multi-size `.ico` (16/24/32/48/256, the 256 PNG-compressed).+- **The live-tile trap:** re-stamping the SAME appId with a new icon updates the title bar + Alt-Tab but NOT the taskbar tile (Win11 bakes it at button creation). To change a live tile, register + stamp a DIFFERENT appId; the button is recreated in ~1s.++---

@@ -0,0 +1,102 @@+---
+name: adom-bridge-sdk-manifest
+description: >-
+  The bridge.json manifest that ships INSIDE your bridge's zip: every field and what Adom
+  Bridge does with it. Use when creating or editing a bridge.json, when a bridge will not
+  spawn or is routed the wrong verbs, or when adding verbPrefixes, spawn kind
+  (python/node/exe/external-http), healthEndpoint, statusVerb, persistent, detect (host-app
+  detection), timeouts, updateManifestUrl, or docs.
+---
+
+
+## bridge.json — the manifest that ships INSIDE your zip
+
+```jsonc
+{
+  "manifest_version": 1,
+  "name": "blender",                        // registry name → verb prefix "blender_"
+  "displayName": "Blender",                 // in-app chip label (the tool's real name)
+  "version": "1.2.0",                       // numeric; a newer CACHE copy supersedes the bundled seed
+  "description": "Drive Blender headless + GUI",
+  "author": "you",
+  "license": "MIT",
+  "docs": "https://wiki.adom.inc/adom/blender-bridge",  // your OWN page (drives skillPkg + hero)
+  "hero": "https://.../hero.png",           // optional; else ab uses your wiki page hero, else a monogram. Ship it at 1.6 aspect (≈2000×1250) — see "Card hero + update cost"
+  "spawn": {
+    "kind": "python",                       // python | node | exe | external-http  (NOT "process")
+    "entrypoint": "server.py",              // the file/exe ab launches; ab AUTO-APPENDS `--port <port>` to argv
+    "port": 0,                              // 0 = ab picks a STABLE port (recommended). Bind 127.0.0.1:<that port>.
+    "persistent": true,                     // ab's supervisor respawns it if it dies
+    "healthEndpoint": "/health",            // INSIDE spawn. ab probes it for the chip (default /health)
+    "stopMethod": "kill",                   // kill | sigterm | graceful_endpoint
+    "killImageName": "python.exe"           // image name for taskkill on stop (kind:python/node)
+  },
+  "verbPrefixes": ["blender_"],             // any verb with these prefixes routes to you
+  "verbs": ["blender_render", "blender_status", "blender_describe"],  // every verb (routing + Verbs tab)
+  "statusVerb": "blender_status",           // verb a caller polls after a long op times out
+  "risk": "exec",                           // v2.0.84 (#50) — gate this bridge for RELAY callers; see note
+  "uninstall": "blender_uninstall",         // REQUIRED — verb ab calls to make you clean up (see below)
+  "updateManifestUrl": "https://wiki.adom.inc/api/v1/pages/blender-bridge/files/blender-manifest.json",
+
+  "timeouts": {                             // v1.9.79 — per-verb HTTP budgets (seconds); see note below
+    "default": 60,                          //   fallback for any verb not matched (absent → ab's global 60s)
+    "verbs": { "render": 600, "export_step": 360 },        // exact BARE verb names (no prefix)
+    "prefixes": [ { "prefix": "export_", "seconds": 120 } ] // fallback rules, first match wins
+  },
+
+  // v1.9.47 cold-start (see "Cold-start tiers" below):
+  "detect": {                               // Tier 2 — how ab DETECTS your HOST APP. ab NEVER installs it.
+    "hostApp": "Blender",                   // omit the whole `detect` block if your bridge brings its own runtime
+    "appPathsExe": "blender.exe",           //   (e.g. pup ships its own browser → no host app)
+    "paths": { "windows": ["%ProgramFiles%\\Blender Foundation\\*\\blender.exe"] }
+  },
+  "prewarm": { "assets": [] }               // Tier 1 — heavy runtime assets ab prewarms (e.g. ["chrome-for-testing"])
+}
+```
+
+- **`verbs`** and **`verbPrefixes`** are arrays of **STRINGS** — bare verb names (`["blender_render", "blender_status"]`), NOT objects. A `{"name": "...", "description": "..."}` object here parses as generic JSON but FAILS ab's strict manifest parse, so **`bridge_install` / `refresh_bridges` now REFUSE it up front** with `errorCode:"manifest_invalid"` + the offending line/column (wiki #107). Before this validation a bad `verbs[]` installed with a phantom `✓` and then silently vanished from `bridge_list` (ab's registry dropped the unparseable manifest). Per-verb descriptions belong in your `<prefix>_describe` output, never in the manifest. If a cached bridge is already in this broken state it shows in `bridge_list` as `status:"invalid"` with an `invalidReason` — fix the field and republish.
+- **`spawn.kind`** is `python` | `node` | `exe` | `external-http` — there is **no `"process"` kind** (and no `"binary"` — `exe` IS the compiled-binary kind), and no `cmd`/`args`/`cwd`. ab launches `spawn.entrypoint` and **automatically appends `--port <port>`** to its argv; your server parses `--port`. (`external-http` = ab doesn't spawn, only probes a port you declare via a `discovery` block.)
+- **Compiled bridges (`kind: "exe"`, wiki #111)** — a Rust/Go/C bridge compiled to a single exe is a first-class citizen, NOT a second tier. ab spawns `entrypoint` (a path inside your bridge dir, e.g. `altium-bridge.exe`) DIRECTLY with `--port <port>` appended: no interpreter provisioning, ~10ms cold start. You get the identical contract as node/python: `ADOM_BIND_HOST` (bind it, never 0.0.0.0), `ADOM_DIRECT_API_URL` + the bridge token env for callbacks, forwarded `X-Adom-Caller-*` headers on every verb, the stable persisted port, health probing, stdout/stderr to `~/.adom/bridge-logs/<name>.log`, PID tracking + reap/respawn supervision. `bridge_readiness` reports `runtime:"none", runtimeReady:true` (nothing to provision). Your release zip is just the exe + `bridge.json` (+ data files); ab sha256-verifies the ZIP against your manifest before extracting, which integrity-gates the exe at install time (a spawn-time re-hash against a same-directory manifest would add no trust boundary, so there isn't one). Set `killImageName` to your exe's basename. Caveat: manifests are single-zip today — no per-platform asset selection — so a compiled bridge is per-OS; fine for a Windows-only host app (Altium), and a cross-platform binary bridge needs per-OS pages until per-platform manifests exist. Reference implementation: `scripts/sample-bridges/hello-rust` (page `adom/hello-rust-bridge`, ~200 lines, the full contract including `describe` + `uninstall`).
+- **`spawn.port: 0`** → ab allocates a STABLE port (persisted across respawns + ab restarts) and passes it. Bind `127.0.0.1:<port>`. NEVER hardcode a port (Hyper-V/Docker silently reserve ranges — see PORTS.md).
+- **`spawn.healthEndpoint`** lives **inside `spawn`** (not at the top level), default `/health`.
+- **`updateManifestUrl`** — the full URL of YOUR manifest on YOUR page. **Declare it in `bridge.json`** so it survives a republish; ab polls it (on launch + every 4h) and auto-updates users. (ab also remembers the install URL in `~/.adom/bridge-install-urls.json` as a fallback, but the declared field is the durable, author-intended path.)
+- **`insidersManifestUrl`** (v2.0.99, optional) — the bridge half of the login-decided release-tier pattern (see the publish skill's "Release tiers" section). Point it at `<product>/version.json` on your org's ONE shared private insiders page (for Adom-published bridges: `https://wiki.adom.inc/api/v1/pages/insiders/files/<product>/version.json`) — never create a per-product private page; the shared page's readers are your insiders. ab probes it FIRST with the desktop user's own session login: 200 + parseable = that desktop follows your insiders tier; any failure falls back to `updateManifestUrl` silently, so a non-insider desktop behaves exactly as if the field did not exist (and abs older than 2.0.99 ignore it entirely). The zip resolves relative to whichever manifest won, fetched with the same login. Keep ONE plain semver per build in both tiers.
+- **`docs`** — point at YOUR dedicated wiki page. ab derives your **skillPkg** (`adom/<slug>`) and your card hero from this. Don't point it at a shared/structural page.
+- **`homepage`** — a **`wiki.adom.inc`** URL (your own page, or `https://wiki.adom.inc/adom/adom-bridge` for the platform). **NEVER `github.com/...`** — GitHub is source-backup only; the wiki is the canonical home. (A `homepage: github.com/adom-inc/adom-bridge` is a stale default to fix.)
+- **`detect` / `prewarm`** — the v1.9.47 cold-start declarations (full rules in "Cold-start tiers" below). `detect` = your HOST APP (ab detects, never installs); `prewarm` = your heavy RUNTIME assets (ab prewarms/auto-installs). A node bridge that ships its deps still works without `prewarm`; declare `prewarm.assets` only for big *downloaded* assets like a browser.
+- **`timeouts`** (v1.9.79) — per-verb HTTP budgets (seconds) ab honors so a SLOW verb (a big export, a cloud open, a long render) isn't cut off before it finishes. Resolution: exact `verbs` (BARE names, no prefix) → first matching `prefixes` → `default` → ab's global 60s. A timeout is **NON-terminal**: ab returns `{stillRunning:true, statusVerb, timeoutSeconds}` and the caller polls your `statusVerb` (so ALSO declare `statusVerb`). **⚠ Before v1.9.79 a third-party bridge was hard-capped at 60s with no way to raise it** — if any of your verbs can run longer, declare `timeouts` (this is the fix). ab reads it with ZERO ab change; the two bundled EDA bridges keep a labeled built-in table only until they declare their own.
+- **`risk`** (v2.0.84, wiki #50) — the risk class of this bridge's verbs, so ab can gate them for a **RELAY (cloud-AI) caller** exactly like a shell verb. Values: `read` | `input` | `exec` | `write` | `network` | `browser-drive` | `config` | `process` | `registry`. ab gates the EXECUTING/MODIFYING classes (`exec`/`write`/`network`/`browser-drive`/`config`/`process`/`registry`) and does NOT gate `read` (or `input`). **Opt-in and safe:** absent = **ungated** (a bridge that declares nothing behaves exactly as before), so you OPT IN to the human-approval prompt by declaring a gated class - nothing changes for the fleet until you do. **Gating is for the REMOTE origin only:** a trusted loopback caller (ah, the local CLI, another bridge) is never prompted; only a cloud/relay caller is. **Coarse today:** the manifest-level `risk` gates ALL of your verbs. The PRECISE per-verb channel is your `<prefix>_describe` output (a bridge author's `describe` can label each verb's risk individually) - that is the authoritative source and where you put a read verb that must stay ungated while your exec verbs gate. Declare the manifest `risk` as your bridge-wide floor, and refine per-verb in `describe`. **Why declare it at all** when a bridge already has ungated loopback access to ab? Because it makes the prompt HONEST: a cloud AI driving your `pup_evaluate` should surface a human approval, and declaring `risk:"exec"` is how ab knows to show one.
+
+---
+
+## `uninstall` — REQUIRED, and ab really does call it
+
+Name the verb that removes **everything your bridge created on the machine**: your host-app
+add-in or plugin (the Fusion add-in lives in `%APPDATA%`, nowhere near ab), your caches,
+downloaded runtimes or browsers, `node_modules`, registry keys, temp dirs. ab removes its own
+`bridges-cache` copy of you; everything outside that only you know about.
+
+```json
+"uninstall": "blender_uninstall"
+```
+
+**This is not advisory.** On an app uninstall ab enumerates every installed bridge and calls
+the verb each one declares here (`bridge_uninstall_all`, fanned out from the installer's
+PREUNINSTALL hook while ab is still alive and can still spawn you to ask). Omit the field and
+ab logs that your bridge left its cleanup to the user, which is exactly the "uninstalling left
+cruft behind" complaint that created this requirement.
+
+Your verb must be:
+
+- **Idempotent and non-interactive.** It runs inside a silent `/S` uninstall, so it can never
+  prompt, and it must succeed when there is already nothing to remove.
+- **Fast.** The cascade is capped (120s for the whole sweep) and failures are skipped rather
+  than retried: an uninstaller that hangs on one bridge is worse than one that leaves a little
+  behind. Do not use the cascade to do slow network work.
+- **Scoped to your own artifacts, strictly.** Never uninstall the host app itself (do not
+  remove KiCad or Fusion), never touch another bridge, never touch user documents. You are
+  cleaning up after yourself, not tidying the machine.
+
+ab calls it with `{"cascade": true, "name": "<your bridge>"}` so you can tell an app-uninstall
+sweep from a user running your verb by hand. Add it to your `describe` catalog and your skill
+like any other verb.

@@ -0,0 +1,442 @@+---
+name: adom-bridge-sdk-publish
+description: >-
+  PUBLISH a bridge: the three artifacts (runtime Release zip + manifest, the container skills
+  pkg, and discovery_triggers), the payload rules that keep each artifact clean (runtime-only
+  / skills-only, media lives on the PAGE), the skill set to ship, USER-skill conventions, the
+  card hero spec, and the full publish checklist. Use when shipping a new bridge version, when
+  bridge_install or an auto-update fails, or when your bridge is not discoverable.
+---
+
+
+## Artifact 1 — the RUNTIME: publish your `.zip` as a RELEASE + a manifest
+
+This is the code ab streams onto the user's machine. Two files on your page:
+
+1. **A versioned Release `.zip`** of your bridge dir (server + `bridge.json` at the zip ROOT + any assets). Ship it as a **Release** (the downloadable, version-pinned artifact), not a loose `/files` blob:
+   ```bash
+   adom-wiki release create adom/adom-bridge-<bridge>-bridge <version> --title "..." --changelog "..."
+   adom-wiki release upload adom/adom-bridge-<bridge>-bridge <version> your-bridge-v<version>.zip --platform any
+   ```
+   (Node bridges: the zip carries SOURCE only — keep `node_modules` out; ab/the seed handle deps. See Prewarm.)
+2. **The manifest JSON** (e.g. `blender-manifest.json`) — identity + where the zip is — POSTed to your page `/files`:
+   ```jsonc
+   { "name":"blender", "version":"1.2.0",
+     "url":"https://wiki.adom.inc/download/adom/blender-bridge/1.2.0/blender-v1.2.0.zip",  // base-relative, extension-agnostic (.bin works where wiki blocks .zip)
+     "sha256":"…", "size":123456, "verbPrefixes":["blender_"], "healthEndpoint":"/health",
+     "updateManifestUrl":"https://wiki.adom.inc/api/v1/pages/blender-bridge/files/blender-manifest.json" }
+   ```
+
+**Users install/update** with ab's `bridge_install {manifestUrl}` → ab downloads the zip, sha256-verifies, unzips into `%LOCALAPPDATA%\Adom Bridge\bridges-cache\<name>\`, rescans, and remembers the URL for auto-update.
+
+**To ship a new version:** bump `version` in BOTH `bridge.json` (in the zip) and the manifest, re-`release upload` the zip, re-POST the manifest. Users auto-get it on the next 4h poll, or immediately via `refresh_bridges {name}`. **A bundled SEED** (a `plugins/<name>/` folder shipped in ab's NSIS) is the offline/first-run fallback; your published cache copy with a higher `version` supersedes it (cache-over-bundled, version-aware). ⚠ **A `release upload` REPLACES a same-platform asset ONLY when the FILENAME is IDENTICAL** — a different name (a version bump `-v1.2.0` → `-v1.3.0`) ADDS a second asset, leaving a stale zip on the release. Keep ONE asset per release: overwrite the same filename, or `adom-wiki release delete-asset <owner/slug> <ver> "<old-filename>"` after a rename. (A stale extra won't break the manifest-URL install, but it clutters the release.)
+
+---
+
+## Artifact 2 — the SKILLS pkg: container-side docs (`.claude/skills` / `.codex/skills`)
+
+Your runtime runs on the user's DESKTOP; the AI driving it runs in a cloud/WSL2 CONTAINER. That container needs your **consumer SKILL.md** locally to know your verbs. Ship it as its own **`adom-wiki pkg`** (skills only, NO binaries):
+
+**Layout** (reference: `adom/adom-wiki-skillpack`):
+
+- **The pkg carries ONLY your USER skill(s).** Each is a real `skills/<name>/SKILL.md`. A ROOT `SKILL.md` (required by the registry) is the pack entry point: `user-invocable: true`, a `description` full of trigger words. Large surface → a core user skill + user sub-skills, but **every skill in the pkg is a *user* skill.**
+- **DEV + PUBLISH skills do NOT go in the pkg — they live in your source repo** (a developer gets them by cloning to edit the bridge). Do NOT list them in `files[]`, and do NOT "scope" them in with `user-invocable:false` (that still ships them and bloats every container install).
+- **Declare `dependencies:{"adom/adom-bridge":"^1.9.x"}`** in `package.json` — `pkg install` resolves it npm-style, so installing your bridge's skill pkg also pulls the ab CLI + core skills the container needs to drive you.
+- **Each sub-skill's body opens with a `Parent skill:` line** (first line after the frontmatter): `Parent skill: **adom-bridge-<bridge>-bridge**`.
+- **List every user-skill path EXPLICITLY — no globs — in `package.json` `files[]` AND `install.sh`/`uninstall.sh`** (one `install_skill <dest> <src>` line each, kept in sync). The publish linter REQUIRES explicit listing. (The old "use `skills/**`" advice is dead.)
+
+```bash
+# Stage dir: ROOT SKILL.md + skills/<name>/SKILL.md per USER skill (dev/publish stay in the repo),
+# package.json {name:"adom-bridge-<bridge>-bridge", version, discovery_triggers,
+#               dependencies:{"adom/adom-bridge":"^1.9.x"},
+#               files:[ every USER-skill path, explicitly ], scripts:{install,uninstall}}.
+# TWO traps that still bite — verify each with `tar tzf` before publishing:
+#  1. ⚠ pkg pack/publish HONORS the stage dir's .gitignore — a gitignored skills/ ships
+#     a 3 MB tarball with ZERO skills. Set .gitignore aside across pack+publish, restore after.
+#  2. ⚠ Keep the tarball LEAN — NO release zip, NO src/ tree, NO hero PNGs (it was 16 MB
+#     before guards). Skills + docs only.
+adom-wiki pkg pack                       # then: tar tzf <tgz> → every skills/<name>/SKILL.md
+                                         #   listed in files[] present, ZERO binaries
+adom-wiki pkg publish --org adom         # publishes adom/adom-bridge-<bridge>-bridge
+```
+
+**`skill_count` on your page counts the USER skills your published PKG carries** — so it should be SMALL (1 for a single-skill bridge, a handful for a core + sub-skills). If it looks inflated, you probably shipped dev/publish skills that belong in the repo instead. The metric is NOT "SKILL.md files in the repo," so a `type:skill` page can read `skill_count: 0` while its repo holds many — don't chase parity across page types (wiki-side quirk).
+
+A container gets it **without anyone asking**:
+- `bridge_install` returns `skillPkg` + `installSkill` (ab derives `adom/<slug>` from your `docs`) and the `_hint` tells the AI to run it.
+- **`adom-bridge sync_skills`** installs every connected desktop's bridge skillPkgs (the CLI also runs it once/day in the background), so a container that connects a week later self-heals your skill.
+- The wiki page's **Skills tab** lists the skills your pkg ships, so the page itself advertises them.
+
+**Install to BOTH agent homes.** A container may run Claude OR Codex — your pkg's `install.sh` must deploy the user skill to **`~/.claude/skills/`** AND **`~/.codex/skills/`** (Codex is a real second skills home now). `adom-wiki pkg update` keeps both fresh.
+
+### ⭐ REQUIRED: say on your PAGE that `pkg install` gives SKILLS, not the bridge
+
+Your page carries **two artifacts that look interchangeable and are not**, and users (and AIs) reasonably assume `adom-wiki pkg install adom/<your-bridge>` installs the bridge. **It does not.** Installing the package alone gives skills with no bridge; `bridge_install` alone gives a bridge whose calling AI has no skills. Most setups want both, and nothing on a default bridge page says so.
+
+**So state it, in ONE plain sentence, in both your package `description` and your README.** Keep this line, or something equivalent:
+
+> This package installs the bridge's SKILLS into your container so your AI knows how to drive it; Adom Bridge loads the bridge runtime itself from the release zip.
+
+**Keep it to one sentence.** The package `description` renders as your page subtitle AND the text under the Install card, so a multi-paragraph architecture essay there actively hurts: it buries the one fact a visitor needs. (ab-core overshot exactly this and had to trim it back.) The long version belongs in your README body, not the card.
+
+⚠ **Empirically, neither card renders a per-item caption today** (verified in-page 2026-07-07): the release title/changelog does not surface on the Download card, and the package description surfaces only as the page subtitle, never at the Install card itself. Setting both fields is still correct hygiene, and they do show on the Releases tab, but do not assume the cards self-explain until the wiki exposes a caption slot (filed as `adom/wiki` #93).
+
+---
+
+## Artifact 4 (OPTIONAL) — the container-side DASHBOARD CLI: your bridge's web surface
+
+Proven end-to-end by fusion-bridge v1.9.42 and blessed as an SDK facet (wiki #81). This is OPTIONAL - a bridge is complete without it - but if your bridge has a user-facing surface (status LEDs, setup, settings, demos), **this is where it belongs.**
+
+**Why the container and not the Windows box.** The user's AI already lives in the container, the container already reaches every ab box over the relay via the `adom-bridge` CLI, and the container already has a port proxy that can hand any browser a URL. So a dashboard that lives there aggregates ANY number of machines through a CLI the user already has, needs no new protocol, and needs no web server on the user's PC. The bridge on the box stays the single source of truth; the dashboard is a thin, honest aggregator that SHELLS bridge verbs. Putting the web surface on the Windows side would mean a second server, a second port to negotiate, and a second thing that can be stale.
+
+**How it ships (the bit people get wrong).** The binary is a **platform-tagged RELEASE asset**, not tarball content - the same `PKG_VS_RELEASE` rule as every other binary:
+
+```bash
+adom-wiki release upload <owner>/<slug> <ver> <bin> --platform linux --arch x64
+```
+
+Your pkg's `install.sh` then downloads it from `https://wiki.adom.inc/download/<owner>/<slug>/<ver>/<bin>` into `/usr/local/bin` (fallback `~/.local/bin`). One version everywhere, and `pkg update` carries the dashboard forward with the skills.
+
+**The verb contract - standardize on these exact names** so an AI that has driven one bridge's dashboard can drive yours:
+
+```
+<bridge>-dashboard serve [--port <p>] [--target <box>] [--print-url]
+<bridge>-dashboard status [--target <box>]     # one-shot JSON of the LED payload
+<bridge>-dashboard health                      # liveness
+```
+
+`--print-url` must print the URL as its FIRST line (that is what a Dock Bar `await:"url"` step reads). All human-facing output is `OK:` / `ERROR:` / `Hint:`.
+
+HTTP surface: `GET /api/status` (the LEDs), `POST /api/action {action,args}`, `GET /state`, `/console`, `/health`.
+
+**⭐ EVERY LED carries a `_hint` naming the exact verb that fixes it when red.** This is the same THE-ONE-PRINCIPLE rule as verb output, applied to the dashboard: it is a discovery surface for an AI as much as a UI for a human. A red LED that only says "not connected" makes the AI guess; one that says "not connected - run `<prefix>_start`" makes it act.
+
+**Dock Bar integration** - a dock manifest at your page repo root: step 1 `adom-wiki pkg install <page>` with `skip_if: command -v <bridge>-dashboard`, step 2 `serve --print-url` with `await:"url"`. Works today against the shipped Dock SDK.
+
+### The full author contract - so you never clone kicad and diff again (wiki #103)
+
+The bits above are enough to WIRE a dashboard; this is the field-by-field so a from-scratch bridge does not reverse-engineer it from another bridge's tree. Two ownership notes first, because they decide what is safe to copy:
+
+- **The dashboard binary, its verbs, and its HTTP surface are YOURS** (this SDK). Copy these exactly.
+- **The dock MANIFEST is Hydrogen's Dock SDK contract, NOT ab's** - Hydrogen's dock reads it and launches your dashboard. So the manifest's filename and fields are defined by the Dock SDK, and this section is a convenience copy, not the source of truth. **⚠ The filename has drifted:** older bridges ship `dockbar.json`, current guidance is `dock.json` (`dock_manifest 1.1.0`). **Confirm the current name + fields against the live Dock SDK / `dock-dashboard` skill before you ship** - do not trust this SDK as authoritative for a contract another app owns (same "relay, don't reimplement" rule ab follows for Hydrogen state).
+
+**The dock manifest** (at your page-repo root) - shape as bridges ship it today:
+
+```json
+{
+  "dock_manifest": "1.1.0",
+  "say": ["Fusion 360 bridge", "electronics package proofs"],   // short strings the dock shows as the card's blurb
+  "webview": { "title": "Fusion 360", "favicon": "https://wiki.adom.inc/<owner>/<slug>/files/favicon.png" },
+  "health": { "url": "/api/status", "poll_seconds": 5, "timeout_ms": 2000 },
+  "launch": {
+    "mode": "container_command",
+    "steps": [
+      { "run": "adom-wiki pkg install <owner>/<slug>", "skip_if": "command -v <bridge>-dashboard" },
+      { "run": "<bridge>-dashboard serve --print-url", "await": "url" }   // await:"url" reads the FIRST stdout line
+    ],
+    "on_ready": "open_webview",
+    "ai": { "prompt": "Drive the <app> dashboard", "thread": "<bridge>-dash", "submit": false }
+  }
+}
+```
+
+**`GET /api/status` - the LED payload your dashboard serves.** Per-facet objects plus a rollup, so the dock can render a row of LEDs and one summary dot:
+
+```json
+{
+  "facets": [
+    {
+      "label": "Fusion",                 // the LED's name
+      "state": "green|yellow|red|gray",  // gray = unknown/not-probed
+      "detail": "connected, 2 docs open",// one human line for the hover
+      "_hint": "not connected - run fusion_start",  // ⭐ the EXACT verb that fixes a red LED (THE-ONE-PRINCIPLE)
+      "short": "OK"                      // <=6 chars for the compact tile
+    }
+  ],
+  "rollup": { "state": "yellow", "short": "1 warn" }   // the single dot when the card is collapsed
+}
+```
+
+Every red/yellow facet MUST carry a `_hint` naming the verb that clears it - the dashboard is a discovery surface for an AI as much as a UI for a human.
+
+**The rest of the HTTP surface:**
+- `GET /events` - **Server-Sent Events**; push a `status` event whenever a facet changes so the dock updates without polling (the `health.poll_seconds` above is the fallback, not the primary path).
+- `POST /api/action {action, args}` - the buttons. Each action shells a bridge verb and returns `{ok, detail, _hint}`; never hold app-specific state in the dashboard, it is a thin aggregator over your verbs.
+- `GET /state`, `GET /console`, `GET /health` - as listed above.
+
+**ONE APP, ONE DASHBOARD** (from the Dock SDK): one dashboard binary per host app, aggregating every box that runs your bridge via `--target`; do not ship a second dashboard for the same app. And the **serving asymmetry** holds: the dashboard runs in the CONTAINER (where the AI and the relay already are), never on the Windows box - see "Why the container and not the Windows box" above.
+
+**On the `bridge scaffold-dashboard` generator you asked for:** a good idea, and deliberately NOT built here. A generator that emits a working `dock.json` + dashboard stub would bake THIS SDK's copy of Hydrogen's manifest, so it would drift the moment the Dock SDK changes a field - exactly the coupling the ownership note above avoids. If a generator ships, it belongs with the **Dock SDK** (which owns the manifest) and keyed off your verb prefix, not in ab. Contributing the Altium dashboard back as a second reference implementation is the more useful move - two worked examples beat one generated stub for a contract this young.
+
+### Four traps this pattern hit in ~50 real releases (fusion, 2026-08-19)
+
+**1. Tarball size, and `git status` will not warn you.** A publish failed at **51.8 MB against a 50 MB limit** because the Rust `target/` directory was being swept into the tarball. `target/` is not in git, so the working tree looked clean and nothing surfaced the problem until the registry refused the publish. **The packer honours `.gitignore`, so add your build output directory to it BEFORE your first publish.** (Same mechanism, opposite direction, as ab's own trap where `.gitignore` silently DROPS staged content - `.gitignore` is the packer's manifest either way, so always `pkg pack` and inspect the tarball before `pkg publish`.)
+
+**2. Version triples drift silently.** Each release touches six files across three independent version streams: `BRIDGE_VERSION` + `bridge.json` (the bridge), `dashboard/Cargo.toml` + `install.sh`'s `DASH_VERSION` (the binary), and `page.json` + `package.json` (the pkg). A mismatch fails at INSTALL time, not build time, which means your user finds it. **Ship a `make release` style script rather than documenting the ritual** - six files kept in sync by hand is a bug with a schedule.
+
+**3. `package.json`'s slug MUST equal the page slug.** A mismatch publishes into a namespace nobody installs from, and it succeeds, so there is nothing to notice.
+
+**4. Recompute the manifest's sha256/size AFTER the zip is built and BEFORE the manifest is pushed.** Obvious in hindsight, easy to invert once you script it, and the symptom is `bridge_install` failing a hash check on a perfectly good zip - which reads as a corrupt download rather than a stale manifest.
+
+**Where this sits relative to the other artifacts:** 1 = the runtime zip + manifest (the Windows box), 2 = the skills pkg (the container's docs), 3 = discovery triggers, 4 = this. It does not replace any of them, and a dashboard is never a substitute for rich `_hint` output on the verbs themselves - the AI reads verb output constantly and opens a dashboard rarely.
+
+## ⛔ Payload rules — both artifacts are RUNTIME-ONLY / SKILLS-ONLY. Media lives on the PAGE.
+
+This is the single easiest way to hurt every one of your users, and it is invisible from your machine.
+
+**The real case (fusion, caught 2026-07-19):** `adom/fusion-bridge`'s release zip was **16.7 MB, of which ~15.3 MB was demo MP4s, screenshots and repo docs**. Every user's machine streamed that on `bridge_install`, and again on every auto-update. Stripped to runtime-only it is **456 KB — 97% smaller — with zero functional change.**
+
+Nobody was careless. The zip was built from `git ls-files` (or by zipping the repo), which sweeps in exactly the things that legitimately belong on your WIKI PAGE: heroes, screenshots, demo videos, architecture diagrams, long-form docs.
+
+**Three destinations, three payloads:**
+
+| destination | carries | never carries |
+|---|---|---|
+| **Release `.zip`** (streamed to every user's machine) | server code, handlers, add-in/plugin code, `bridge.json`, resources the runtime READS AT EXECUTION TIME | media of any kind, screenshots, demo videos, README/CHANGELOG, `.github/`, tests, dev docs, `node_modules` |
+| **pkg tarball** (extracted into every container's `$HOME`) | `SKILL.md` + your USER `skills/**`, `install.sh`/`uninstall.sh`, `package.json`, `page.json` | media, the release zip, `src/`, dev/publish skills, binaries |
+| **the PAGE** (`/files`, served to browsers) | hero, screenshots, demo videos, diagrams, long-form docs | binaries (see the release/pkg split) |
+
+Media on the page is served to a browser when someone looks at it. Media in an artifact is **pushed to every machine that installs you**, forever, on every update. That is the whole distinction.
+
+**How to not do this:**
+
+1. **Build the zip from an explicit whitelist**, or from `git ls-files` **minus** media and repo cruft:
+   ```bash
+   git ls-files | grep -viE '\.(mp4|webm|png|jpg|jpeg|gif|svg|zip)$' \
+                | grep -viE '^(screenshots|docs|demo|\.github)/' \
+                | grep -viE '(CHANGELOG|PUBLISHING)\.md$' | zip -@ my-bridge-v1.2.3.zip
+   ```
+2. **Know your number.** A bridge runtime zip is normally **well under 1 MB**. If yours is bigger, that is not automatically wrong (a bridge with real runtime assets can be), but it IS your cue to **list the contents and justify every entry** before uploading.
+3. **Inspect before you publish, every time — this is the step that actually catches it:**
+   ```bash
+   unzip -l my-bridge-v1.2.3.zip | sort -k1 -n -r | head -20   # biggest files first
+   tar tzf my-pkg.tgz                                          # zero media, zero binaries
+   ```
+   Sorting by size is the trick: the offender is always at the top, and a glance tells you whether you are shipping code or a video.
+4. **Keep `files[]` an explicit text-only list** (every USER-skill path, no broad globs). A glob is how images get in.
+
+**A publish-time lint would catch this automatically** and has been asked for: a warning when a release asset or pkg tarball contains video/image files, with the size breakdown. That lives in the wiki CLI, not in your bridge, so until it ships **the inspect step above is the only thing standing between you and a 15 MB download on every user's machine.**
+
+**Reference:** the ab-core pkg itself follows this — 18 files, zero `.png`/`.mp4`/`.exe`, and its `docs/**` images were removed from `files[]` in 2026-07-06 for exactly this reason (4.56 MB of PNGs, including a 1.38 MB hero, were shipping inside every container install).
+
+---
+
+## Artifact 3 — DISCOVERABILITY: `discovery_triggers` so a plain request finds you
+
+The wiki has an **auto-discover** index, and it is the difference between a usable bridge and an **invisible** one. Declare `discovery_triggers` (the phrases a user actually says) on your page, and a plain request matches them via `adom-wiki discover find` / the in-app discovery an AI runs.
+
+```bash
+adom-wiki discover triggers adom/adom-bridge-<bridge>-bridge --add "open my pcb" "export gerbers"  # add triggers
+adom-wiki discover preview --json "open my pcb design"          # what would surface + the SCORE + WHY
+adom-wiki discover find    "screenshot my website"              # the live find an AI runs
+```
+
+**How scoring actually works (measured 2026-06-30 — know this or you'll guess wrong):**
+- `score = 3×(distinct triggers matched) + 1×(tags) + 1×(brief/text)`. **Trigger matches dominate (3× each);** tags/title/brief barely move it.
+- **NO TRIGGERS = INVISIBLE.** A bridge with a perfect title ("Adom Bridge - Blender Bridge") + a matching tag scored **ZERO** for the literal query *"blender"* — it never appeared in `discover preview`. The scorer ignores title/tags when there are no triggers. **Every shipped bridge MUST carry `discovery_triggers` or it cannot be found by the discovery an AI uses.** (`discover search` full-texts the readme, but that is NOT the path discovery takes.)
+- **More good triggers = higher rank.** Each match is +3, so 10 user-task phrasings beat 2. The healthy bundled bridges carry **30-40** triggers; a struggling one had 14 — all dev jargon — and lost EVERY user query.
+
+**The cardinal rule: triggers are USER-TASK phrasings, NOT dev jargon.** A real user types *"open my pcb design"* / *"export gerber files"* / *"design a circuit board"* — NOT *"reverse bridge"* / *"kicad_bridge_call"* / *"fork the kicad bridge"*. A trigger list full of architecture terms scores 0 on every real query (kicad's actual failure: 7/7 user queries missed, and the **Fusion** bridge out-ranked KiCad on PCB queries because Fusion happened to carry a couple of fuzzy "pcb"/"export" triggers). Put **10+ everyday task phrasings first**; technical aliases (verb names) are a small minority at the end.
+
+**VET it — never ship triggers you didn't test:**
+1. Write **5-7 queries a typical user would type** to get your tool (these double as your page `sample_prompts`).
+2. `adom-wiki discover preview --json "<each query>"` → read `data.scoring[]` (array order = rank). **You must land in the top 3.** (Rate-limited: space calls ~2 s; expect a 429 after ~25.)
+3. For every query where you're NOT top-3, **add that exact phrasing as a trigger** and re-test. If a sibling bridge out-ranks you on a shared word (Fusion vs KiCad on "pcb"), add MORE exact phrasings so your 3×-per-trigger total wins.
+
+**Claim YOUR niche — don't poach a sibling's territory.** Discovery routes by whose triggers match; if two bridges match a query the user lands on whichever has *more* triggers, NOT whichever is actually right. So your triggers must describe what YOU are genuinely best at — and you must LEAVE OUT cases a sibling owns. **Canonical example: logging into a site / filling a form on a signed-in page is the native-browser extension's job — it drives the user's REAL browser with their REAL logins — NOT puppeteer's.** Pup is a fresh Chrome-for-Testing profile with no saved logins; it's for *non-login* automation (scraping, screenshots, testing, public pages). So pup must NOT carry `log in` / `fill a form on a site I'm signed into` triggers, and native-browser MUST. When a task needs a capability you DON'T have, make your `discovery_pitch` *point at the bridge that does* — and tell the user to install it (e.g. "for logged-in form-filling, install the native-browser extension") — rather than claim it and do it badly.
+
+- **`discovery_pitch`** is the one-liner the snippet quotes back to the AI — auto-generated from `discovery_triggers` + `discovery_pitch`, **no separate upload step.** Make it an INSTRUCTION, not a tagline.
+- **Make your `brief` / `discovery_pitch` an instruction** — it's what the AI reads from the find result. Tell it the next moves: *"…check `adom-bridge bridge_list` to confirm the bridge is installed; if it is, drive its `<prefix>_*` verbs. If the container lacks the skill, `adom-wiki pkg install adom/adom-bridge-<bridge>-bridge` (or `adom-bridge sync_skills`)."*
+
+### The end-to-end flow your three artifacts enable
+
+User says *"show me my app in pup"* → the AI:
+1. `adom-wiki discover find "show me my app in pup"` → your bridge surfaces (Artifact 3).
+2. `adom-bridge bridge_list` → is your bridge installed in ab? If not, `bridge_install {your manifestUrl}` (Artifact 1).
+3. Is your skill pkg installed in THIS container (`~/.claude/skills/` or `~/.codex/skills/`)? If not, `adom-wiki pkg install adom/<slug>` / `sync_skills` (Artifact 2).
+4. Drive your verbs — guided by the **rich hints you return** (the principle at the top).
+
+---
+
+## The SKILL SET you should ship (not one SKILL.md — a small library)
+
+Don't cram everything into one file. Ship **three kinds** of skill, each with a different reader **and a different home** — the USER skill goes in the pkg; the DEV and PUBLISH skills stay in your source repo:
+
+1. **A PUBLISH skill — lives in your source REPO** (for the bridge's OWN cloud/dev thread): how to cut the Release zip, POST the manifest, bump versions, publish the skills pkg (with the `.gitignore` trap), set `discovery_triggers`, and re-seed ab's bundled copy. This keeps *your* future self from getting the publish dance wrong.
+2. **A DEV skill — lives in your source REPO** (for whoever edits the bridge): architecture, the verb contract, how to test locally, the boundary with ab — and, front and center, **the rich-hints-in-output rule**: *the AI never reads this file; it reads your verb OUTPUT, so every verb must return `_hint`/`_next`/`related`/`pitfalls`.* Make that the loudest thing in the dev skill.
+3. **USER skill(s) — shipped in your pkg** → the container: how a cloud AI drives your verbs to get real work done. **If the verb surface is large, split it:** a small **core USER skill** (the 80% workflow + a pointer to the sub-skills) plus **sub-skills** by area (e.g. `…-recording`, `…-electronics`, `…-aps-search`). A 2,000-line monolith won't get read; a tight core skill that names the sub-skills will. (Pup ships exactly this shape: a core bridge skill + user sub-skills.)
+
+**Only the USER skill(s) go in your pkg** (Artifact 2), each a real `skills/<name>/SKILL.md`. **The DEV + PUBLISH skills stay in your source repo** — a developer gets them by cloning to edit the bridge; they are NOT in the pkg's `files[]`, and you do NOT "scope" them into the pkg with `user-invocable:false` (that still ships them and bloats every container install). Open-vs-closed source doesn't change this — it only sets whether your repo's dev/publish files are publicly readable.
+
+**Start from the templates — don't write these from scratch.** Fill-in-the-blanks files for each of the three skill kinds, generalized from pup's battle-tested set. **Fetch them from THIS page** (they used to be cited as a path inside ab's own repo, which is private, so the pointer was unfollowable for exactly the cloud authors it addressed — fixed 2026-07-25):
+
+```bash
+BASE=https://wiki.adom.inc/api/v1/pages/adom-bridge-sdk/files
+curl -fsSL $BASE/bridge-dev-template.md        -o dev-skills/<bridge>-dev.md
+curl -fsSL $BASE/bridge-publish-template.md    -o dev-skills/<bridge>-publish.md
+curl -fsSL $BASE/bridge-user-skill-template.md -o skills/<bridge>/SKILL.md
+```
+
+- **`bridge-dev-template.md`** — architecture, the rich-hints rule, caller-provenance handling (logging the thread, arbitrating sessions, forwarding on your own ab callbacks).
+- **`bridge-publish-template.md`** — the whole release/pkg/discovery dance and every trap (the `.gitignore` set-aside, the lean-tarball rule, release-and-pkg-ship-together).
+- **`bridge-user-skill-template.md`** — the consumer skill, already encoding all eight conventions below plus the `--ai-thread` identity line.
+
+Copy the one you need, swap `<bridge>`/`<prefix>` for your names, delete what doesn't apply. **How your skills reach a container in the first place** (the runtime installs on the desktop, the skills install in the container, and the two travel by different routes): [`docs/bridge-skill-propagation.md`](https://wiki.adom.inc/api/v1/pages/adom-bridge-sdk/files/docs/bridge-skill-propagation.md) on this page.
+
+---
+
+## USER-skill conventions — what every consumer skill must teach (from pup's shape)
+
+These eight patterns are what make a cloud AI actually succeed with your bridge on the first try. The user-skill template encodes them; bake them into whatever you ship:
+
+1. **Open with a "FIRST-TIME / COLD-START — read before you panic" section.** A fresh PC may lack your runtime or owe a one-time download, and the AI's default failure mode is to declare defeat. Lead with a **response → meaning → what-you-do** table that frames `*_installing` / `not_ready` as EXPECTED, keyed off `errorCode` (not prose).
+2. **Standardize two cold-start verbs: `<prefix>_readiness` and `<prefix>_prewarm`.** `readiness` → `{ready, installing, installProgressPct, lastError}`; `prewarm` kicks off setup without real work and supports `{"wait":true}` to block. Gives every bridge a uniform "poll until ready, then proceed" loop. (Complements the runtime-side Prewarm section above.)
+3. **End the `description:` frontmatter with a `Trigger words:` line** mixing verb names AND plain-English phrases a user would actually type ("take a screenshot of", "log into"). This is what makes a user-invocable skill activate — and it feeds your `discovery_triggers` (Artifact 3).
+4. **Include a short "Core verbs" table** (Command | Description | Key args) for the 80% path, and point at `<prefix>_describe '{}'` for the full machine-readable catalog. The AI reads the table to act fast; `describe` is the completeness escape hatch — don't bloat the skill with every verb.
+5. **"Background by default — don't disrupt the user."** Your bridge drives the AI's workspace, not the user's screen: lower/un-focus after automation, never force-foreground except to SHOW the user something, nudge via a taskbar flash (`*_alert_window`) instead of stealing focus. Standardize `*_lower_os_window` / `*_raise_os_window` / `*_alert_window`.
+6. **Teach "`ok:true` is not enough" — verify what you did.** Verbs that return on operation *start* (not completion) need a cheap post-check (an eval/read verb, else a screenshot) before reporting success — 404s, login walls, and empty states land silently.
+7. **Sessions: reuse-don't-reopen + stable identifiers.** Tell the AI to `*_status` before opening a new session (especially after compaction), reuse a match, and pick a stable `profile` so logins/state persist across runs. Prevents duplicate windows and the lost-login footgun.
+8. **"Surface `_hint` verbatim."** Every verb returns an actionable `_hint` on not-ready/failure; instruct the AI to relay it to the user unchanged, and branch on the stable `errorCode` (not the prose). This closes the loop with THE ONE PRINCIPLE at the top — the hint IS your UI.
+
+---
+
+## Card hero + update cost — two gotchas that bite
+
+**Hero: ship a 1.6-aspect image, or ab crops the OG-card fallback.** ab's bridge card renders the hero in a banner that is `aspect-ratio: 1.6` with `object-fit: cover`. So:
+- Ship a **1.6-aspect** hero (≈**2000×1250**), full-bleed — like pup & kicad. It fills the banner cleanly.
+- If you ship **no** hero (`bridge.json` has no `hero` AND your wiki page has no `hero_path`), ab falls back to your page's **auto-generated OG card** (1200×630 = **1.90** aspect, the social-card size). `cover` scales that wider image to the banner's height and **clips the sides** — the left text panel gets cut off. (That cropped, off-center look is the tell of a hero-less bridge — it's not an ab bug.)
+- Fix: publish a real hero at 1.6 (the `adom-wiki` page hero, or a `hero` URL in `bridge.json`). Verify by opening your card in ab — the title/text must not be clipped.
+
+**Update cost: keep the Release zip source-only; re-seed the NSIS bundle in lockstep.** When a user clicks the card's "↑ v…" update badge, ab downloads your Release zip into the cache and (for a node bridge) provisions deps:
+- **The Release zip MUST be source-only — no `node_modules`.** ab provisions node deps at spawn: it **reuses the bundled seed's `node_modules` via `NODE_PATH`** when the cache version ≤ the seed version (instant), and runs a real **`npm install`** only when the wiki version is *newer* than the bundled seed.
+- So a wiki version much newer than your bundled seed forces a **cold `npm install`** on the next spawn — slow for a heavy tree. **When you publish a new Release, bump the bundled NSIS seed in lockstep** (same version) so most users get the instant NODE_PATH reuse, not a cold install.
+- ab (**v1.9.52+**) never blocks the UI on this: the update downloads straight to cache (no wasteful seed re-copy — the old code deep-copied pup's 73 MB / 4698-file seed and then discarded it, the "updating… forever" hang), the badge shows live progress (`downloading…` → done) with a 30s "installing…" fallback, and your bridge **keeps serving the old version** until the new one is ready. A lean zip + a lockstep seed is what keeps it *fast*.
+
+---
+
+## Publish checklist (the whole modern flow)
+
+1. **Page** — `adom-wiki page create adom/adom-bridge-<bridge>-bridge` with a hero + an **instructional `brief`** + **`discovery_triggers`**.
+2. **Runtime** — `release create` + `release upload` the versioned `.zip`; POST the manifest to `/files`; set `updateManifestUrl` in BOTH the zip's `bridge.json` and the manifest. **Before uploading: `unzip -l <zip> | sort -k1 -n -r | head` — runtime only, no media.** *(→ Payload rules)*
+3. **Skills pkg** — stage ROOT SKILL.md + `skills/<slug>/SKILL.md` (core USER skill + sub-skills) + `discovery_triggers`; `pkg pack` (**`tar tzf` it — skills only, zero media/binaries**) → `pkg publish --org adom` (mind the `.gitignore` trap). Your `description` carries the one-sentence "this installs SKILLS, not the runtime" line. *(→ Artifact 2)*
+4. **Discovery** — `discover triggers` to confirm; `discover preview "<a real user phrase>"` to confirm you surface.
+5. **Re-seed ab's bundled copy** (ab-core thread, not you) — extract your Release zip over `plugins/<name>/` keeping bundled deps; ships in the next NSIS as the offline fallback.
+6. **Verify** — `bridge_install {manifestUrl}` on a desktop → `bridge_list` shows your `version` + `skillPkg`; `bridge_check_updates` reaches your page; a container `sync_skills` pulls your USER skill; `discover find "<phrase>"` surfaces you with an instructional brief.
+
+**Reference bridge = pup** (`adom/pup-bridge`): live `discovery_triggers`, a skills pkg with a core + sub-skills, a Release zip + manifest with `updateManifestUrl`, a bundled seed with prewarmed `node_modules`, and rich per-verb hints. Copy its shape. (`scripts/sample-bridges/hello-python` + `hello-rust` are the minimal skeletons.) KiCad, Fusion, Blender, Puppeteer, and the **native-browser** bridge (in the `adom-browser-extension` repo) are cloud-owned — don't edit them from the ab repo. When an ab release changes a bridge-facing contract **— or when THIS SDK doc itself changes —** ab posts a migration notice to **each** of their wiki discussions (`kicad-bridge / fusion-bridge / blender-bridge / pup-bridge (their pre-rename slugs until those threads rename)` + `adom-browser-extension`). **Author-facing takeaway: watch your bridge's own wiki DISCUSSION/issues list — that's where an "SDK changed, please re-audit against the billboard" notice lands, and where you reply with your plan or blockers.** It's the only channel ab uses to reach you; ab never edits your repo.
+
+## Declare your agent-permission posture — so the classifier approves instead of blocks (adom/wiki#156)
+
+Claude Code's auto-mode runs a PERMISSION CLASSIFIER over every shell command an agent
+issues, and it judges unknown CLIs purely on the words in the command string. Your bridge's
+verbs reach it as opaque strings like `adom-bridge yourprefix_do_thing '{...}'` - so without
+help, the classifier blocks or nags on every call, and users accumulate piles of one-off
+approvals that never generalize (a measured container had 121 of them).
+
+The registry fixes this, and YOU own your part: declare an **`agent_permissions`** block in
+your skills pkg's `package.json`, and `adom-wiki pkg install / update / uninstall` composes
+every installed package's declarations into a managed region of the container's
+`~/.claude/settings.json` (regenerated, never appended - uninstall cleans up for free).
+
+```jsonc
+"agent_permissions": {
+  // Deterministic prefix rules for your own binaries only.
+  "allow_bash": ["your-cli"],
+  // Natural language the classifier reads. DESCRIBE YOUR VERBS: name the read-only
+  // ones and say what they read; the classifier can only be as smart as this text.
+  "allow": [
+    "your-cli query verbs (yourprefix_status, yourprefix_list, yourprefix_get): read-only queries against <what>; they change nothing."
+  ],
+  // Verbs that spend money, destroy data, or execute code: keep the container-side
+  // prompt for them even though your own gate also fires.
+  "soft_deny": [
+    "your-cli mutate verbs (yourprefix_delete, yourprefix_order): they modify <what>."
+  ],
+  // One line of context so the classifier knows what your CLI IS.
+  "environment": [
+    "your-cli is <one sentence>, installed by the Adom registry."
+  ]
+}
+```
+
+The rules that make it safe and effective:
+
+- **Enumerate your verbs with descriptions.** A bare "allow my-cli" teaches the classifier
+  nothing; "these named verbs are read-only catalog queries" lets it approve confidently
+  and keep prompting on everything else. Keep the read/mutate split honest - the split IS
+  the value.
+- **Only speak about your own binaries and verbs.** A package cannot grant anything beyond
+  its own surface, `hard_deny` is not package-writable, and composition/ordering belong to
+  the client - do not try to game them.
+- **Bridge verbs get a second gate anyway.** Anything your bridge routes through Adom
+  Bridge to the user's desktop hits ab's own human-approval model (caller identity,
+  per-call reason, Activity Log). Say so in your `environment` line: the classifier
+  approving the CONTAINER call is the first of two gates, not the only one.
+- Keep it current: when you add or rename verbs, update the block in the same publish - a
+  stale allow line describing a verb that now mutates is worse than none.
+
+## Release tiers — insiders first, public on a human's words (a design pattern any bridge can run)
+
+A bridge with real users eventually needs two speeds: people who should get every build the
+moment it exists, and people who should only see releases a human deliberately promoted.
+The pattern below gives you that with nothing but a wiki page and your updater — the tier is
+decided by LOGIN, never by a setting, and a public user never learns the early tier exists.
+
+**Pick one of three postures:**
+
+| Posture | Who it fits | What you publish |
+|---|---|---|
+| **Public-only** | most bridges | exactly what this skill already describes; no early tier, nothing changes |
+| **Two-tiered** | a bridge with outside users who need stability while you iterate | every publish goes to YOUR private page; the public page moves only on a human's attested promote |
+| **Private-only** | a bridge whose whole audience is one team or one machine fleet | the private page IS the page; there is no public tier and never a promote |
+
+**The six mechanisms of the two-tiered posture:**
+
+1. **ONE shared private insiders page per publisher — never a page per product.** The tier
+   lives on your organization's single shared private page as `<product>/version.json`
+   (one folder per product); the people who can read that page are, by definition, the
+   insiders, and one access list covers the whole fleet. Do NOT create a new private page
+   for your product — request write access to the shared page instead (a page per product
+   multiplies access lists and bloats the wiki; for Adom-published bridges the shared page
+   is `adom/insiders`). Only a publisher with no org page at all creates one — and then
+   still ONE page for everything they publish.
+2. **The manifest probe.** Your updater tries the private page's manifest first with the
+   USER'S OWN session token as Bearer; 200 + parseable = follow it. Anything else (no
+   token, 403, 404, network, parse) = follow the public manifest, silently — a probe
+   failure is not a failure, and a public user must stay oblivious (no error, no visible
+   log, no Settings entry). Scope the Bearer strictly to your private page's URLs so the
+   token never reaches another host. No file on the machine records the tier: log out and
+   the next check is public; get page access and the next check is insiders.
+3. **Publish defaults private.** Your release script writes the private manifest unless
+   explicitly told otherwise, and REFUSES the public manifest without an attestation
+   (below). Archive every publish (manifest + artifacts) so promote and rollback work
+   from the record.
+   **The BYTES always live on your product's own PUBLIC page.** Upload the installer/zip
+   as an ordinary release asset there even for an insiders-only build — a version is only
+   DISCOVERABLE through a manifest, and the insiders manifest is private, so public
+   hosting leaks nothing a promote wouldn't. Never upload artifacts to the shared insiders
+   page (it carries only `<product>/version.json` manifests); both tiers' manifests point
+   at the SAME public URL, so promote is a manifest edit, never a byte copy.
+4. **Promote and rollback carry the human's words.** Moving a release to the public tier
+   requires the human's exact words, stored IN the manifest (`promotion_attestation`,
+   plus `promoted_by`/`promoted_at`), so the record of who approved the rollout travels
+   with the release. An AI passes the words through verbatim or does not promote — never
+   on its own judgment, never because a sweep was green. Rollback re-points the public
+   tier at an archived release, fast, and still records the words
+   (`rollback_attestation`).
+5. **One plain semver per build, in both tiers.** The same version string identifies the
+   same signed artifact whether it is serving insiders or public — no `-beta` suffixes,
+   no per-tier renumbering. The tier is WHERE the manifest lives, never WHAT the version
+   is called; promote moves a version, it never rewrites one.
+6. **Publish the pkg alongside EVERY release row — insiders included.** Release rows and
+   pkg rows share ONE version namespace per page, and the pkg resolver picks the max
+   satisfying row and then FAILS if that row has no tarball — so a release-only insiders
+   row silently breaks every constraint `pkg install` of your page for everyone (the
+   wiki#22 failure mode). Ship the pkg with the release, always. Consequence, until the
+   registry grows login-tier dist-tags (adom/wiki#168): `pkg latest` — what registry
+   installs follow — effectively tracks your INSIDERS tier. That is the accepted,
+   documented cost of keeping constraint installs working; do not "fix" it by holding
+   the pkg back to promote time.
+
+Both tiers serve the SAME signed artifacts; the only difference is which manifest a
+machine follows.

@@ -0,0 +1,121 @@+---+name: adom-bridge-sdk-runtime+description: >-+  The RUNTIME contract for a bridge: Adom Bridge provisions Node/Python for you and you MUST+  bind loopback (ADOM_BIND_HOST) so no firewall prompt appears; plus prewarm, the cold-start+  tiers, host-app detection and the bridge_readiness probe, the health endpoint and status-+  chip contract (led/summary/tooltip), the lifecycle verbs users drive, and the logging split+  (ab owns the file, you own the volume). Use when your bridge fails to spawn, shows the wrong+  LED, is slow on first call, or needs a runtime it cannot assume exists.+---+++## Runtime contract — ab provisions Node/Python; you bind loopback (v1.9.63 / v1.9.69)++**The single most important change for a Node or Python bridge.** As of ab **v1.9.63** you no longer bootstrap your own interpreter, and you MUST bind loopback. Four rules:++1. **Don't bootstrap your own Node/Python.** ab owns a global, portable, **no-UAC** runtime under `~/.adom/adom-runtimes/`: a system install if one's on PATH, else a portable copy it downloads + prewarms in the background on first launch. ab spawns your `entrypoint` with that interpreter **by absolute path**. So **delete every `winget install node` / `desktop_install_node` / "please install Python" / self-download step** from your bridge and its skills. `spawn.kind: "node"|"python"` IS your runtime declaration — ab reads it and provisions the runtime. Anyone can check status with the **`runtimes`** verb (`state ∈ absent|installing|ready|failed`, `source ∈ system|cache`, version). ab pins the version (Node 22.11.0 / Python 3.12.13 today) — need a different major? ask the ab-core thread; don't ship your own.++2. **Bind `ADOM_BIND_HOST`, never `0.0.0.0`.** ab passes an **`ADOM_BIND_HOST`** env var (always `127.0.0.1`) to every bridge it spawns. A bare listen that defaults to `0.0.0.0` pops a **Windows Firewall "allow access?" dialog** on first run — and ab's hard guarantee to users is **no firewall prompt by default**.+   - Node: `server.listen(PORT, process.env.ADOM_BIND_HOST || '127.0.0.1', cb)`+   - Python: `HTTPServer((os.environ.get('ADOM_BIND_HOST', '127.0.0.1'), PORT), Handler)`++3. **Ship the Release zip source-only — ab installs your deps, and v1.9.69 makes it bulletproof.** A Node bridge's zip carries SOURCE only (no `node_modules`). ab reuses the bundled seed's `node_modules` via `NODE_PATH` when versions match, else runs **`npm install --include=optional`** for you with the managed runtime's own npm. **As of v1.9.69 ab puts the managed runtime's dir on the child PATH for that install AND for your spawned process** — so a dep's postinstall / `node-gyp` / `prebuild-install` that shells out to a **bare** `node`/`npm`/`npx` (puppeteer's own `node install.mjs`, `sharp`, `keytar`, `better-sqlite3`, `bcrypt`) resolves even on a machine with **no system Node**. **You do NOT add the runtime to PATH yourself** — ab guarantees it. (Python: the interpreter dir + `Scripts/` are on PATH too, so pip can build wheels.)++4. **Bundle deps in your SEED for an instant first spawn.** Source-only zip + a bundled-seed `node_modules` at the same version = ab reuses the seed via `NODE_PATH` (instant); a wiki version newer than the seed forces one cold `npm install` (now PATH-correct, but slower). Bump the seed in lockstep with each Release.++5. **`ADOM_SESSION_TOKEN` (ab v2.1.57, optional): your bridge's OWN Adom session token, when the user configured one.** If the user set `bridge_session_tokens: {"<your-bridge>": "<token>"}` in ab (via `settings_set`; the key is your bridge's runtime name, the same one `bridge_log_read` uses), ab injects it into your spawn env as `ADOM_SESSION_TOKEN`. Use it for calls that must be attributed to your bridge's own identity on wiki.adom.inc / Adom Anywhere (`adom-wiki pkg install`, wiki writes, app runs) instead of borrowing the human's token. Rules: it is a SECRET - never log it, never put it in a `_hint` or any verb output, never write it to disk. Absent means the user did not configure one: degrade gracefully (public/unauthenticated behavior, or report `session_token_required` in your output so the AI can ask the user to set one). ab only DELIVERS the token; the identity behind it (for example a "Grok Bot" account) is created by a human in Carbon.++**Net:** declare `spawn.kind`, bind `ADOM_BIND_HOST`, ship source-only. ab does the rest — no UAC, no firewall prompt, no `'node' is not recognized`.++---++## Prewarm — make the first call instant++A cold first call that pays multi-minute setup (npm install, downloading a runtime, a heavy import) blows the caller's timeout. Pay that cost in the background BEFORE the user asks:++- **Bundle deps in your SEED.** Pup ships a bundled `node_modules/` in its NSIS seed so a fresh PC can spawn with no `npm install`. When you re-seed from a Release zip, keep the bundled deps.+- **Idempotent warm-up.** Make spawning + a no-op health/setup pass idempotent so a background prewarm is a no-op once warm.+- **ab prefetches for you on first launch — standalone AND embedded (Hydrogen-bundled) — gated on availability.** (Pup's Node + Chrome-for-Testing prefetch runs once per install in both modes as of ab v1.9.45.) If your bridge needs a heavy runtime, expose a cheap idempotent "ensure ready" path ab/your seed can trigger, and surface a clean `errorCode` (e.g. `node_not_found`) when a prereq is missing so the AI can install it (`desktop_install_node`) instead of hanging.+- **`pup_readiness`-style verb.** Offer a fast verb that reports `{ready:true|false, …}` so a caller (or a fresh-PC test) can confirm warmth without triggering work.++---++## Cold-start tiers, host-app detection & the `bridge_readiness` probe (v1.9.47)++A bridge has TWO kinds of dependency, and **ab treats them OPPOSITELY.** Get this right or a first-install probe (e.g. Hydrogen's "what tools do I have") triggers a slow install at the worst moment.++**Tier 1 — your RUNTIME (Node, Python, your own browser download): ab prewarms + auto-installs it.** This is your plumbing. On first boot ab **provisions** Node/Python in the background — a **portable, no-UAC** copy under `~/.adom/adom-runtimes/` (or a system install if one's on PATH), **NOT winget/MSI** (see **Runtime contract** above) — and prewarms heavy assets you declare. You may also download your own runtime asset (pup downloads Chrome-for-Testing) — fine, it's yours. **But do it in the BACKGROUND: a `*_status` / `*_readiness` / ANY probe verb must NEVER block on a heavy download.** Spawn your server fast (it usually doesn't need the asset to *start*), kick the download off detached, and report `state:"warming"` until ready. A synchronous-download-on-first-verb is the exact footgun this release fixed (pup's 150 MB Chrome fetch used to block the probe).++**Tier 2 — the HOST APP (KiCad, Fusion, Altium, …): ab DETECTS it by default and installs it ON REQUEST — never pre-emptively, and NEVER by telling the user to do it themselves.** Two rules that sound opposed but aren't:+- **Don't install it unasked.** A multi-GB app nobody asked for is rude, so by default ab only DETECTS presence (a machine with KiCad belongs to a KiCad user; EDA users are mono-tool — a Fusion user isn't a KiCad user). ab won't prewarm/spawn your bridge while the app is absent — a resource decision, not a "go away."+- **But the cardinal Adom rule overrides everything: the AI does EVERYTHING for the user — it must NEVER tell the user to do something the AI can do itself.** So your bridge MUST know how to install the host app (`desktop_install_kicad` / winget / your own install verb) and just DO it the instant the user wants it. **Your "not installed" hint must OFFER to install it** ("KiCad isn't installed — want me to install it for you?"), then do it on a yes — it must NEVER say *"download it from kicad.org."* Pointing the user at a manual download is the breach.++**Bridge install LEVELS — how eagerly each bridge gets onto the machine. The AI ALWAYS does the install; the level only sets the TIMING/CONSENT:**++| Level | Bridge(s) | Behavior |+|---|---|---|+| **0 · Built-in / MUST** | Hydrogen (`hd`) | The platform itself — the editor ab lives in. Always present; not "installed" by ab. |+| **1 · Fundamental — pre-emptive** | Puppeteer (`pup`) | Browser automation is foundational to Adom. ab pre-installs its RUNTIME (Node + Chrome-for-Testing) ASAP on first boot, no asking. |+| **2 · Recommended — proactive offer** | native-browser (the browser EXTENSION half) | The user's REAL logged-in browser (login/forms). Since v1.9.142 the DESKTOP BRIDGE half ships bundled in the ab installer (0.2 MB, zero deps, `persistent:true` — its extension-free verbs like `nbrowser_open_os_window`/`nbrowser_profiles`/`nbrowser_os_windows` work day one). What remains level-2 is the in-browser EXTENSION: ab/the bridge proactively SUGGESTS it and it installs on a yes (a browser-extension step the user confirms), unlocking full in-page drive. |+| **3 · On-request host app** | KiCad, Fusion, Altium, … | Detect by default; NEVER pre-install (huge app, rude unasked). The moment the user wants it, the AI installs it AUTOMATICALLY (winget / `desktop_install_*`) — NEVER tells the user to do it manually. |+| **4 · Explicit third-party** | any `bridge_install`'d bridge | The user opts in by installing it. |++The through-line: **the AI never makes the user do something it can do itself.** The only knob is *when* — pre-emptive (pup), proactively-offered (native-browser), or on-request (host apps).++**Declare both in `bridge.json`:**+```json+"detect": {                          // Tier 2 — how ab finds your HOST APP (detection only)+  "hostApp": "KiCad",+  "appPathsExe": "kicad.exe",        // optional: Windows App Paths registry lookup (most reliable)+  "paths": {                         // optional: candidate paths, %VAR% expanded, one * = a version dir+    "windows": ["%ProgramFiles%\\KiCad\\*\\bin\\kicad.exe"],+    "macos":   ["/Applications/KiCad/KiCad.app"],+    "linux":   ["/usr/bin/kicad"]+  }+},+"prewarm": { "assets": ["chrome-for-testing"] }   // Tier 1 — heavy runtime assets ab prewarms + reports+```+A bridge that brings its OWN runtime (pup ships its own browser) **omits `detect`** — it has no external host app. ab infers the runtime from `spawn.kind` (node→Node, python→Python).++**The read-only probe: `bridge_readiness`.** ab aggregates all of this into ONE side-effect-free verb the setup AI calls — it **never spawns a bridge, never installs/downloads**. Per bridge: `{hostApp, hostAppInstalled, runtime, runtimeReady, assets, state}` where `state` ∈ **`ready`** (use it) | **`warming`** (runtime ok, a heavy asset still downloading in the background — re-poll, don't trigger it) | **`needs-runtime`** (node/python installing) | **`no-app`** (host app not installed → not relevant here). Plus a top-level `edaToolsInstalled` list — the one-line answer to "what EDA tools do I have." **Tell your users (in your skill): for a "what do I have / is it ready" question call `bridge_readiness`, NOT your `*_status` verb** — a `*_status` may spawn your bridge; readiness never does.++Your two own cold-start verbs (above) still apply: `<prefix>_readiness` (read-only `{ready, installing, installProgressPct, lastError}`) + `<prefix>_prewarm` (`{wait}`-able). Those drive YOUR bridge specifically; `bridge_readiness` is the ab-level aggregate that detects + summarizes across all bridges without spawning any.++---++## Health + status chip++Your `/health` (200) makes the chip green. Optionally return `led` (`green`/`yellow`/`red`), `summary` (short label), `tooltip` (full hover). ab owns the **offline** (gray) state when your endpoint is unreachable — you can never assert offline.++## Lifecycle verbs (ab gives these to USERS — know them to guide users)++`bridge_install {manifestUrl}` · `bridge_list` · `bridge_info`/`bridge_detail {name}` · `bridge_log_read {name, sinceOffset?}` · `bridge_kill {name}` · `bridge_pause {name}` · `refresh_bridges {name?}` · `bridge_check_updates`. A bridge installed via `bridge_install` auto-updates with no further opt-in; `updateManifestUrl` in `bridge.json` makes it durable across republish.++**"My bridge keeps exiting and I can't see why" (read this).** Your own stdout log truncates on every respawn, so a crash-then-restart erases its own cause. `bridge_log_read` therefore also tails **ab's lifecycle audit log** for your bridge, a separate append-only file (`~/.adom/bridge-logs/<name>.ad.log`) that survives respawns, shown under an `===== ab bridge lifecycle =====` header. It records every spawn, reap, duplicate-collapse, and `bridge_kill` with the reason, so you can tell "ab reaped it as a duplicate" or "the `bridge_kill` verb stopped it" or "it was reaped before a fresh spawn" apart from "it crashed on its own." If the audit log shows ab never stopped it, the exit is inside your process.++## Logging: ab owns the FILE, you own the VOLUME++Every bridge writes to stdout, ab captures it, and nobody asks the volume question until someone's log is a firehose. The split:++- **ab owns the FILE.** ab spawns you and captures stdout/stderr, so the file and its rotation are ab's. A bridge cannot rotate a file another process holds open, and bounded logs have to be a platform guarantee rather than per-author boilerplate.+- **You own the VOLUME.** How much you emit is the half a tidy platform cannot fix for you.++*(READING the log is the section immediately above: `bridge_log_read` plus ab's separate lifecycle audit. This section is about what you WRITE.)*++**Do NOT write your own parallel log file.** Two log files means two sources of truth and double the disk for the same bytes. pup built one (a rotated `pup.log`) and deliberately reverted it. If you think you need your own log, what you probably want is for ab to scope `bridge_log_read` to your bridge: file that against `adom/adom-bridge` (see "Filing issues against ab" above) instead of forking the log.++**The five patterns that keep a bridge out of firehose territory:**++1. **Never log per-item inside a loop over live state.** This is the single biggest source of volume. A drag-detection check logged one line PER TAB per check, all of them saying "(same)", so a 12-tab window emitted 12 useless lines every time the check fired. **Log the exception (the tab that moved), never the roll call.**+2. **Collapse consecutive identical lines.** Wrap `console.log` once, hold the last message, and emit `^ last line repeated Nx` when it changes. A retry loop then costs 2 lines instead of 200. Collapse only EXACT consecutive repeats, so no distinct event is lost. About 15 lines of code.+3. **Log static facts once per session, not per call.** "no favicon on this page" was emitted on every taskbar-badge update. It is a property of the page, not an event, and because the repeats were not consecutive the collapser could not catch them. Gate it behind a per-session flag.+4. **DO log every incoming verb, one compact line.** This is the one place to ADD volume. A log that records what the bridge DID (park, identity, overlay) but never WHAT WAS ASKED of it cannot answer "what foregrounded this window?" after the fact. Include only the args that change behavior, and skip your own log-read verb so reading the log does not pollute it. Put the caller thread on this line too (the shape is in "Caller provenance" above):++   ```+   [verb] pup_open_window session=parkedge url=https://example.com owner=parktest+   ```++5. **Never let logging throw.** Wrap the whole path in try/catch. A logging failure must not take the bridge down.++---

@@ -0,0 +1,461 @@+---
+name: adom-bridge-sdk
+description: >-
+  START HERE to build a bridge for Adom Bridge - a small local server that adds a namespace of
+  verbs (kicad_, fusion_, pup_, your_prefix_) to Adom Bridge. The orientation skill: the ONE
+  principle (rich _hint/_next in every verb's OUTPUT, because the AI reads CLI output and
+  almost never your on-disk SKILL.md), the three artifacts you publish, where every file
+  lives, the ab-core-vs-author boundary, and a map to the rest of the SDK skill library. Read
+  this first, then load the specific skill for the phase you are in.
+---
+
+
+# Bridge SDK: build, publish, and surface a bridge for Adom Bridge
+
+A **bridge** is a small local program (Python, Node, Rust, anything) that ab spawns and routes a **namespace of verbs** to over HTTP. KiCad, Fusion 360, Puppeteer (pup), native-browser, Blender are bridges. The modern flow has THREE moving parts you own. Get all three right and a cloud/WSL2 container can *discover* your bridge from a plain-English request, confirm it's installed, and drive it with zero tribal knowledge:
+
+1. **Runtime**: a versioned **Release `.zip`** + a **manifest** on your wiki page. ab's `bridge_install` streams it onto the user's machine and spawns it.
+2. **Skills**: an **`adom-wiki pkg`** tarball carrying your consumer SKILL.md(s). A container installs it into `~/.claude/skills/` (or `~/.codex/skills/`) so the AI *there* knows your verbs.
+3. **Discoverability**: **`discovery_triggers`** on your wiki page so a user saying *"open my app in pup"* surfaces YOU via `adom-wiki discover find`.
+
+> **THE ONE PRINCIPLE THAT MATTERS MOST: read this before anything else.**
+> **The AI almost never reads your on-disk SKILL.md. It ALWAYS reads the OUTPUT of a CLI call.**
+> So your leverage is in the **`_hint` / `_next` / `related` / `pitfalls` you return on EVERY verb response.** A verb that returns `{success:true}` and nothing else leaves the AI guessing and retry-looping. A verb that returns *what just happened, the obvious next verb, the related verbs, and the pitfall to avoid* gets driven perfectly on the first try. ab relays every field of your response **verbatim** to the calling AI. Treat each verb's output as the documentation the AI will actually read. (Your SKILL.md is for the *human* author + the rare AI that does read it; your verb OUTPUT is for the AI in the loop.)
+
+---
+
+## ⛔ STOP — the LINE OF DEMARCATION: ab is an operating system, your bridge is an app
+
+**If you remember one thing from this SDK: a bridge NEVER modifies ab. Every line of logic specific
+to your app lives in YOUR bridge. The correct amount of ab-core change for a new bridge or a bridge
+feature is ZERO.** This is not style — it is the architecture, and violating it breaks the thing that
+makes bridges work.
+
+**ab is an operating system for the desktop.** Like a kernel it does two jobs: it provides **generic,
+app-agnostic primitives** (windows, screenshots, input, files, shell, WSL, taskbar/window identity,
+jump lists, notifications, tunnels) that know nothing about any specific app — `desktop_set_window_identity`
+does not know what a browser is, it applies whatever icon/name/AUMID *you* hand it — and it **loads,
+unloads, reloads, and updates bridges on the fly** (`bridge_install`, the wiki auto-sync, hot respawn).
+ab stays deliberately stable and generic so it almost never has to change for a new bridge.
+
+**Your bridge is an app running on that OS** — a fluid, hot-loadable asset with its own process, its
+own skills, its own wiki page, its own release cadence entirely independent of ab. It owns **100% of
+the logic specific to its host app or tool**, and when it needs the desktop to *do* something it
+**calls one of ab's existing generic verbs** over the loopback direct API (see `adom-bridge-sdk-callback`).
+The payoff: your bridge ships and updates from your own page with **no ab release**. The moment your
+code lives in ab you have chained your feature to ab's release train and made the kernel carry your
+app's weight — the opposite of what a dynamic, loadable bridge is for.
+
+### The three AI failure modes (all seen live, 2026-08-28)
+
+A capable coding AI slides into all three. Guard against them explicitly:
+
+1. **Reproducing capability ab already ships.** Before writing ANY desktop capability — and absolutely
+   before proposing an ab change — search ab's existing verbs (`/verbs`, the `adom-bridge-verbs` skill,
+   or just ask the ab thread). Real case: a bridge shipped a **2,668-line ab-core module** re-implementing
+   window identity, taskbar overlay, and jump lists that ab **already provided generically** and another
+   bridge was **already using**. The check is one grep. Do it.
+2. **Baking your app's name into ab.** The same case hardcoded a forced `Adom.<App>.` AUMID namespace,
+   app-named jump-list labels, and an app-named router verb into ab-core. **If ab would end up knowing
+   your app's name, the line has been crossed.** Your app-specifics stay in your bridge, which passes
+   its own appId / icon / labels *into* ab's generic verbs. **If you catch your AI editing `src-tauri/`, stop.**
+3. **Pulling app-AWARE correctness logic UP into the host.** The subtlest one. Strict window binding —
+   "bind this operation to an exact HWND + owner PID + process-start so I never act on the wrong window" —
+   *feels* like it belongs in the kernel because it is about windows. It does not: doing it requires
+   knowing **how your app creates its windows** (process/window/creation-time relationships, correlating
+   a spawned browser to a session). That is narrow app knowledge and **ab must never have it.** Do the
+   identify-and-verify work in YOUR bridge, then hand the resolved HWND + your identity to ab's dumb,
+   generic paint verbs. **The bridge decides *which* window and proves it; ab never learns why.**
+
+### The rare, legitimate exception — and the process
+
+Sometimes a bridge genuinely needs a **generic ab primitive that does not exist yet.** That is real and
+welcome. **What is gated is the CONTENT, not the channel:**
+
+1. **Confirm it doesn't already exist.** Search the verb surface first. Most "I need a new verb" is
+   "there's already a generic one."
+2. **Apply the two-part test:** *could a completely unrelated app use this verb unchanged?* AND *can ab
+   implement it knowing nothing app-specific?* **If either answer is no, it belongs in your bridge** — no
+   channel makes it acceptable. When an existing generic verb is close but not strict enough for you, ask
+   for a **generic hardening of that verb**; never fork an app-specific copy of it, and never ask ab to
+   absorb app-aware logic (failure mode 3).
+3. **Then pick the channel by who you are:**
+   - **Adom team** — **just send a PR.** It is the efficient path and it is welcome. The PR must still
+     pass the two-part test and touch only generic surface: a reviewer's first question is *"does ab now
+     know anything about your app?"* **Keep it on a BRANCH and leave it for review — never self-merge to
+     `main`.** ab ships to the whole fleet from `main` and the ab thread builds/signs/publishes releases
+     from it, so an unreviewed merge silently becomes everyone's next auto-update — and if both branches
+     bump the version you get **two different builds carrying the same version number**, which the updater
+     can never heal (see BUMP LAST in the release ladder). A branch costs nothing and makes both
+     impossible.
+   - **Third-party author** — **file a discussion on the `adom-bridge` page** proposing the verb as a
+     generic contract, and the ab thread adds it (or invites a PR once the contract is agreed).
+
+> **Being on the team does not widen the line — it only shortens the path to proposing something that was
+> already generic.** A team PR that adds an app-named namespace, app-named labels, or app-aware binding
+> logic to ab-core gets the same answer as anyone else's: build it in the bridge.
+
+### Your bridge's KEYWORD — the short word a user says
+
+**Declare ONE short, unambiguous keyword and use it everywhere.** A user says *"open my app in **pup**"*
+and the AI must resolve that single word, through ab's layers, to your skills and verbs. That only works
+if the word is declared and consistent. Requirements:
+
+- **Short and speakable** (`pup`, `kicad`, `pw`) — this is what a human types in chat, not your product name.
+- **Unambiguous** — avoid a word that collides with a common term or another bridge's niche.
+- **Consistent everywhere**: your `bridge.json` `name`, your **verb prefix** (`<keyword>_…`), your
+  `discovery_triggers` phrasings, your README's opening line, and your card. If the keyword is `pw`, the
+  verbs are `pw_*` and the README says so in the first paragraph.
+- **State it explicitly** in your README's first section: *"Say **pw** to the AI to reach this bridge."*
+  A keyword agreed in conversation but written nowhere does not exist.
+
+---
+
+## ⭐ Developing against a live ab: PIN YOUR BRIDGE FIRST (`bridge_dev_mode`, ab 2.1.13+)
+
+ab auto-updates every installed bridge (a 4h sweep, an on-launch sync, on-use
+auto-update, and refresh_bridges) - which means the moment you start editing
+your bridge's files IN its installed cache, a release can land on top of your
+uncommitted work and destroy it. Before you modify a cache, run:
+
+```bash
+adom-bridge bridge_dev_mode '{"name":"<your-bridge>","on":true}'
+```
+
+While pinned, EVERY automatic update path skips your bridge (and
+`download_and_install` refuses as a second guard); the user sees an amber
+"dev pin" badge on your bridge's card so the frozen state can never rot
+silently. When you are done: `{"on":false}` and the next sweep pulls the
+current release back over the cache. `bridge_list` shows `devPinned` per
+bridge; pin flips are written to your bridge's lifecycle audit
+(`bridge_info.adLifecycle`).
+
+## ⚠ PITFALLS — real failures from real bridges, and how to avoid each
+
+Every entry here happened. They are listed in the order they tend to bite, and each is written as
+**symptom → why it happens → fix**, because the ones that hurt are the ones that look fine while you
+are making them.
+
+### 1. Building your feature into ab instead of into your bridge
+
+**Symptom:** you have a PR against `adom-bridge` for something your bridge needs. **Why:** the capability
+sounds like a desktop primitive ("I need the taskbar to show my app"), so extending the host feels
+natural — and if you never enumerated ab's existing verbs, it also feels *necessary*. **Fix:** the
+capability is almost certainly already generic in ab (window identity, taskbar overlay, jump lists,
+screenshots, input, files, notifications). Call it. See the LINE OF DEMARCATION above. *Measured cost of
+getting this wrong: a 2,668-line ab-core module duplicating verbs another bridge was already using.*
+
+### 2. Your app's name ending up in ab
+
+**Symptom:** ab-core contains your app's name — a forced `Adom.<YourApp>.` namespace, app-named labels,
+an app-named router verb. **Why:** you needed *some* identity string, and hardcoding it in the host was
+the shortest path. **Fix:** every app-specific value is an ARGUMENT your bridge passes into a generic
+verb. `grep -ri "<yourapp>" <ab>/src-tauri/src/` must return nothing.
+
+### 3. Pulling app-AWARE correctness logic up into the host
+
+**Symptom:** you want ab to do strict binding — "act only on the exact HWND + owner PID + process-start,
+never the wrong window." **Why:** it is about windows, so it feels like kernel work. **Fix:** it is not —
+doing it well requires knowing *how your app creates its windows* (process/window timing, correlating a
+spawned process to a session), which is precisely the knowledge ab must not carry. Resolve and verify in
+YOUR bridge; hand ab a resolved HWND for its dumb generic paint verbs. **The bridge decides *which*
+window and proves it; ab never learns why.** This is the subtlest one on the list — it passes the
+"is it generic?" sniff test and still fails the two-part test.
+
+### 4. Shipping something nobody can RUN
+
+**Symptom:** your work sits unreviewed and untried. **Why:** it is only runnable if someone builds and
+runs a *modified core ab* — nobody will do that to try out a feature — or your releases are all
+dev/updater-ineligible candidates, so `bridge_install` has nothing to resolve. **Fix:** a bridge's whole
+value proposition is that **anyone can install it in one command and use it in a minute.** Ship at least
+one qualified, updater-eligible release with its runtime `.zip`, and keep 100% of the feature inside the
+bridge so trying it never requires touching ab. *A change people must review is worth far less than a
+thing people can just use.*
+
+### 5. Shipping something nobody can SEE
+
+**Symptom:** your README is all prose; a reader cannot tell what your bridge does or whether it works.
+**Why:** you can see it working on your own machine, so the gap is invisible to you. **Fix:** screenshots
+of the real outcome, and for anything VISUAL (taskbar tiles, jump lists, overlays, rendered output)
+**before/after** shots — prose cannot convey it and nobody can verify it otherwise. pup's README carries
+13 images, kicad's 8, plus demo videos; a new bridge shipped **0** for an entirely visual feature and its
+reviewer had no way to evaluate it at all. `desktop_screenshot_window` makes capturing this scriptable.
+**This matters most for a bridge aimed at outside users: an internal bridge can lean on the author being
+in the room, but for everyone else the page IS the product.**
+
+### 6. A keyword that exists only in conversation
+
+**Symptom:** you and a colleague agreed the bridge is "pw", but an AI never resolves it. **Why:** the word
+was never written into `bridge.json`, the verb prefix, the discovery triggers, or the README. **Fix:**
+declare it once and use it in all four places — see "Your bridge's KEYWORD" above.
+
+### 7. Stale naming and a missing page kit
+
+**Symptom:** your page reads as abandoned next to the other bridges. **Why:** slugs and copy written
+before the rename (**Adom Bridge**, not "Adom Desktop"), no root `SKILL.md` (only a `skill-package/`
+directory), no 1.6-aspect hero (so ab cover-crops the OG-card fallback and clips it), and none of the
+standard kit (`install.sh`/`uninstall.sh`, `CHANGELOG.md`, `PUBLISHING.md`, billboard art). **Fix:** the
+page-identity block of the self-audit checklist (`adom-bridge-sdk-audit`) is a literal punch list for this.
+
+### 8. Assuming ab will forward what it never received
+
+**Symptom:** you add an arg to a verb and it silently does nothing. **Why:** something in the chain
+rebuilt the payload from a fixed allowlist instead of forwarding verbatim. **Fix:** round-trip test it —
+send an unknown arg and have your bridge echo its received keys. Every arg you send must arrive.
+
+---
+
+## Where every file lives: the two artifacts, their deps, and which skills go where
+
+**Two DISTINCT artifacts, two DIFFERENT homes, two DIFFERENT consumers. Crossing them is the #1 inconsistency across bridge repos, so pin it here before anything else.** (Live audit 2026-07-06: fusion + pup do this right; kicad had **61** loose `adom-bridge-kicad-v*.zip` on `/files` + a `mesa-llvmpipe-x64.zip`; blender dumped 2 loose zips too.)
+
+| | **RUNTIME artifact** (Artifact 1) | **SKILLS pkg** (Artifact 2) |
+|---|---|---|
+| **What it is** | your bridge's actual CODE | your consumer `SKILL.md` docs |
+| **Runs on** | the user's **DESKTOP** (ab spawns it) | **nothing runs it** (docs the CONTAINER reads) |
+| **Published as** | a versioned **Release** (`release create` + `release upload --platform any`) | an **`adom-wiki pkg`** (`pkg publish --org adom`) |
+| **Installed by** | `bridge_install {manifestUrl}` → ab streams, unzips, spawns | `pkg install adom/<slug>` / `sync_skills` → `~/.claude/skills` + `~/.codex/skills` |
+| **Contains** | server code + `bridge.json` at the zip **ROOT** + assets. **Node: SOURCE ONLY, no `node_modules`.** | ONLY: ROOT `SKILL.md`, `skills/<name>/SKILL.md` (user skills), `package.json`, `install.sh`, `uninstall.sh`. **Text only: the whole tarball should be a few KB.** |
+| **NEVER contains** | the skills pkg | **ANY image (hero / screenshots: those are WIKI PAGE assets, see below), any binary, the Release zip, `src/`, `node_modules`, dev/publish skills, or the server's npm deps.** If `tar tzf` shows a `.png`/`.jpg`/`.zip`/`.exe`, you bundled bloat. Remove it. |
+| **its `package.json`** | (node) the **bridge SERVER's runtime deps** ab installs at spawn: `dependencies:{ puppeteer, … }` | the **pkg manifest**: `files[]` (user skills), `discovery_triggers`, scripts, **AND `dependencies:{"adom/adom-bridge":"^1.9.x"}`** (the container needs the ab CLI + core skills to drive you), but NOT the server's npm deps |
+
+**Yes, a node bridge has TWO `package.json` files and they are NOT interchangeable.** One rides inside the Release zip and lists the **bridge server's** runtime deps (puppeteer, sharp, ...) that ab installs on the *desktop* at spawn. The other is the **pkg manifest** in the skills tarball: it lists your user-skill `files[]` + `discovery_triggers` AND declares **`dependencies:{"adom/adom-bridge":"^1.9.x"}`**. `pkg install` resolves that npm-style, so installing your bridge's skill pkg also pulls the adom-bridge CLI + core skills the container needs to drive you. What the pkg manifest must NOT list is the **server's** npm deps (those are desktop-side, in the zip). Put them there and you bloat every container install, since the container never runs your server.
+
+**Where each file physically lives (this is the map that ends the inconsistency):**
+- **`bridge.json`** → the **root of the Release zip** (ab reads it post-unzip). Carries `version` + `updateManifestUrl`.
+- **The Release `.zip`** → upload it as a **Release asset** (`release upload … --platform any`) and point the manifest `url` at its **release-download path**: `https://wiki.adom.inc/download/adom/<slug>/<ver>/<file>.zip` (verified to serve anon 206). **fusion + pup do exactly this, so copy them.** A loose `/files` blob technically serves too (206), so this is a HYGIENE + right-home rule, not "it won't work": the `/files` store is your git **page repo** (for the manifest, text, images), so a binary there accumulates forever (kicad has **61** stale `-v*.zip`), isn't pinned to a Release, and the `/blob/...` URL is just an **alias of the same blob** (same sha), so you can't tidy it. **⚠ Migrating off `/files` is a SEQUENCE, not a delete:** (1) `release upload` the zip, (2) repoint the manifest `url` at the `/download/` path, (3) verify it serves anon, (4) *only then* `repo rm` the old `/files` copies. **NEVER `repo rm` a zip while your manifest still points at it** (or at its `/blob` alias). That breaks `bridge_install` + auto-update instantly.
+- **The manifest** (`adom-bridge-<name>-manifest.json`, this naming is the consistent one, keep it) → POSTed to your page **`/files`**. Its `url` points at the **Release download** (`https://wiki.adom.inc/download/adom/<slug>/<ver>/<file>.zip`), base-relative + extension-agnostic. `updateManifestUrl` (in the manifest AND in bridge.json) points back at this manifest.
+- **A big RUNTIME ASSET** (a headless-GL pack like Mesa, a browser download) → declare it in **`prewarm.assets`** so ab downloads + manages it, or bundle it in your seed. **NOT a loose `/files` blob**: kicad's `mesa-llvmpipe-x64.zip` on `/files` is the anti-pattern.
+- **Your hero image + screenshots** → **WIKI PAGE assets**: set them on the page (the page's hero / `repo push` the image to the page), **NEVER in the skills tarball.** A container that `pkg install`s your skills never renders a hero, so a bundled hero (a real one was **1 MB**) is pure download bloat on every install. **Do NOT put `hero: docs/hero.png` + `docs/**` in the pkg `package.json`**, because that is exactly what stuffs the image into the tarball.
+
+**The three kinds of skill, and where each goes (this IS the demarcation, one table):**
+
+| Skill kind | Who reads it | Lives in | In the pkg tarball? | Public? |
+|---|---|---|---|---|
+| **USER** (the public / consumer skill) | a consumer AI driving your verbs | your **pkg** | **YES**, that is the pkg's whole job | yes (the pkg is public) |
+| **DEV** | a maintainer editing the bridge | your **source repo** | **NO, never** | only if your repo is public |
+| **PUBLISH** | a maintainer releasing the bridge | your **source repo** | **NO, never** | only if your repo is public |
+
+**The one rule:** the pkg tarball carries **USER skills only**; **DEV + PUBLISH skills live in the source repo.** Do NOT "scope" dev/publish into the pkg with `user-invocable:false`, since that still ships them (pure bloat). Open-vs-closed source only sets your repo's *visibility*; it never changes what's in the pkg. adom-bridge core does exactly this: user/integration skills in the pkg; `RELEASE` / `WIKI_PUBLISH` / `SIGNING` / `AD_RELAUNCH` live only in the source repo.
+
+---
+
+## The boundary: what ab owns vs what YOU own
+
+The #1 mistake is filing ab bugs for bridge issues. The split:
+
+**ab core owns** (don't reimplement): the CLI/relay/`/command` passthrough (ab relays your JSON verbatim, every field); spawning/reaping your process, the **stable port**, single-instance, the persistent-respawn supervisor, cache install + auto-update; host/process facts (running? pid? port?), the status-chip rendering, the GUI card, the activity log; `status`/`_hint` classification for timeouts/disconnects (ab authors those, you never stamp them).
+
+**You own**: your verbs + their behavior + their **rich hints**; your `/health` (+ optional chip fields); your `<prefix>describe` catalog; your wiki page (hero, brief, `discovery_triggers`, docs); your published **manifest + Release zip**; and your **skills pkg**.
+
+If a *bridge verb* misbehaves → fix the bridge. If a *generic ab capability* is missing (a new lifecycle verb, a relay field) → file it against ab, but don't re-absorb the bridge into ab.
+
+---
+
+## ⭐ REQUIRED: every bridge MUST expose a `<prefix>uninstall` verb (John, 2026-08-12)
+
+An Adom employee reported that uninstalling left cruft behind, because ab's uninstaller could remove ab's own files but had no way to clean up what each BRIDGE created. Bridges install their own state OUTSIDE ab's directory: a host-app add-in (the Fusion add-in lives in `%APPDATA%`, not ab's dir), per-bridge caches, downloaded runtimes/models, registry keys, temp dirs. Only the bridge knows where all of that is.
+
+So the contract now requires: **every bridge exposes a `<prefix>uninstall` verb** (e.g. `kicad_uninstall`, `fusion_uninstall`, `pup_uninstall`) that removes EVERYTHING that bridge created on the machine: its add-in/plugin files in host-app dirs, its caches, its registry entries, its temp files, anything outside ab's own `bridges-cache` (which ab removes). It must be:
+- **Idempotent and non-interactive** (safe to call when already clean; never prompt/block, since it runs during a silent `/S` uninstall cascade).
+- **Best-effort per-item** (one un-removable file must not abort the rest; report what was and wasn't removed).
+- **Scoped to your own artifacts ONLY**: never touch the host app itself (don't uninstall KiCad/Fusion), other bridges, or user data.
+
+ab's uninstaller enumerates the installed bridges and calls each bridge's `<prefix>uninstall` before removing ab, so an uninstall cleans up the whole ecosystem. **LIVE as of ab 2.0.84** (it was a stated contract before that but ab did not yet make the call): the `bridge_uninstall_all` verb fans the sweep across the registry, and the NSIS PREUNINSTALL hook invokes it through the bundled CLI while ab is still running and can still spawn your bridge to ask it to clean up. The sweep is capped at 120s and per-bridge failures are skipped, so a slow or broken uninstall verb costs you your cleanup, not the user's uninstall. Declare the verb in your `bridge.json` (an `uninstall` field naming the verb) so ab knows to call it; if absent, ab logs that the bridge left cleanup to the user. Add it to your `describe` catalog and skill like any other verb.
+
+---
+
+## ⭐ REQUIRED: every slow verb reports MEASURED progress - percent, ETA, and cold-vs-warm (John, 2026-08-18)
+
+**This was SUGGESTED on 2026-08-14 and that was not enough: a live Fusion surface button still sat on "starting the app ... cold start can take a couple of minutes", which is a shrug, not data.** A UI cannot draw a progress bar from a sentence, the user cannot tell slow from wedged, and the number never narrows as the work proceeds. So it is now a RULE.
+
+**The shape.** Any verb whose p50 exceeds ~3s returns a `progress` block on the in-progress path AND on the final frame:
+
+```json
+"progress": {
+  "phase": "cold_start",
+  "stepLabel": "Loading the electronics workspace",
+  "percent": 38,
+  "elapsedSec": 27,
+  "estimatedSec": 71,
+  "etaSec": 44,
+  "confidence": "measured",
+  "startKind": "cold"
+}
+```
+
+1. **`percent` is MONOTONIC** - coarse (step N of M) is fine, backwards is not. `null` only when genuinely unknowable, and then `confidence:"unknown"` plus a moving `stepLabel` so the user sees life.
+2. **`estimatedSec` is REVISED as you learn.** A static constant is not an estimate; hit a checkpoint early and the estimate shrinks.
+3. **COLD vs WARM is measured and reported** (`startKind`, and say it in `stepLabel` too: "Fusion is already running - reusing it"). They differ by 10-50x, so one pessimistic sentence covering both is the actual bug. Keep a ROLLING MEASURED HISTORY per phase in your own state dir (last ~5 cold + last ~5 warm, p50/p90), seed estimates from THAT, and expose it in `describe` so a UI can say "typically 45s cold, 3s warm on THIS machine" before the user clicks. That is what makes `confidence:"measured"` true rather than decorative.
+4. **A long verb is POLLABLE and says so:** return `{started:true, jobId, statusVerb:"<prefix>_progress", progress:{...}}` and keep the same block flowing from the poll verb until `done`/`failed`. **Never block silently past your own declared timeout.**
+5. **Terminal frames carry ACTUALS:** `percent:100` + real `elapsedSec` + `measured:{phase, seconds, startKind}` (feeds your history and ab's logs). On failure, name the phase it died in + `failedSteps` so the bar turns red in the right place instead of hanging at 38%.
+
+**ab's side of the deal - what is TRUE TODAY, and WHERE your block gets drawn.** ab forwards `progress` VERBATIM: no parsing, no per-app logic (same generic-renderer rule as the status chip and `stepShot`), so whatever you emit reaches the caller unaltered. **Shipped and verified:** the block survives the round trip through `adom-bridge` to a cloud caller, and the **web-control demo page renders it** - bar, step label, percent/ETA, cold-vs-warm, a dimmed fill when your `confidence` is not `measured`, an amber stalled bar on `blockedBy`, and your `stepShot` frame verbatim as the step's evidence thumbnail.
+
+**The renderer is the WEB, and that is the point.** Your progress is drawn where a person is actually looking: the web-control demo page (`http://127.0.0.1:24681`) is the REFERENCE IMPLEMENTATION, and it exists so wiki.adom.inc can render your bar the same way for real users. **ab's own window deliberately draws NO progress bar** - it is a background agent's console the user barely opens, so a bar there would be effort spent where nobody looks. (ab 2.0.66/67 shipped one by mistake; 2.0.68 removed it. ab still emits the block internally, so a future surface can pick it up with no ab release.) Design for the web surface, not for ab's window.
+
+**Still owed:** ab does not yet report its OWN slow operations in this shape. The SSE `/command/stream` progress you may have seen is ab's RECIPE-STEP runner (step N of M, `usuallySec`), not your block being streamed.
+
+**What that means for you: emit BOTH shapes, because they drive different halves of the bar.** ab reads two, matched on shape alone (never on a bridge name):
+
+1. **The terminal frame** - a top-level `progress` on the slow verb's own response. This is the one `progressContract` already promises, and it always arrives at `percent:100`: by the time the verb answers, the work is done. It is a completion receipt, so on its own it paints a bar that flashes "done" and never moves.
+2. **The live poll** - an **`active[]`** array of those same blocks, one per in-flight phase, returned by your fast progress verb (`<prefix>_progress`) while the slow work is still running. **This is the one that makes the bar MOVE**, because a caller polling once a second produces a stream of rising frames. An empty `active[]` means idle and draws nothing.
+
+If you only ship #1, the user watching your 40-second verb sees nothing until it finishes. When several phases are in flight ab draws the **least complete** one, since the honest answer to "how far along is this?" is bounded by the slowest phase.
+
+**`blockedBy` is the one that earns the most trust.** When the work is parked on a HUMAN - a modal dialog, a login, a save prompt - set it, and ab's status line says "waiting on you: `<what>`", turns the fill amber, stops advancing it, and keeps the bar up instead of timing it out. A bar that keeps sliding while nothing can happen without the user is worse than no bar at all.
+
+**⭐ REQUIRED, and broader than progress: NEVER let a verb time out when the true state is "waiting on a human" - SAY it.** The calling AI cannot see the user's screen; a bare timeout tells it nothing, so it retries or gives up, both wrong. If your verb is blocked on a human action - a permission prompt, an app modal, a login/2FA wall, an OS dialog - return a STRUCTURED non-terminal response that names it, whether or not you are streaming progress: `{ success:false, errorCode:"blocked_on_user", stillRunning:true, blockedBy:"<what the user must do>", _hint:"<how the AI should wait/retry>" }`. This is the same contract ab-core follows for its own blocks (`needs_approval`, `timed_out`+`stillRunning`, `bridge_installing_deps`, `bridge_spawn_failed`) - the caller must always be able to tell "still working / waiting on the user / genuinely failed" apart. A verb that returns a bare transport error or lets the HTTP call time out while a human decision is pending is a bug, not a slow verb. (Learned on wiki #142/#137: a caller left with only a timeout hunts a phantom bug; a caller told "waiting on the user to click Allow" simply waits.)
+
+Why this matters more than a demo page: **ab is the only process that sees every bridge response**, so a cloud AI polling from a container now drives a bar on the USER'S screen. The person at the keyboard finally sees what a remote agent is doing to their machine - something no container-side UI can provide.
+
+The demo verbs already prove the shape works (`<prefix>_demo_progress` streams percent/stepLabel/elapsedSec/estimatedSec and the web-control page draws a live bar from it). The gap was that ONLY the demo verb did it. Instrument the rest: `*_start` (the cold-start case that triggered this), `*_show_*`, install/export/build.
+
+Tracking: kicad-bridge#32, fusion-bridge#32.
+
+---
+
+## Background: the original duration-hint suggestion (John, 2026-08-14) - now folded into the rule above
+
+Launching KiCad, waiting for a Symbol Editor or a 3D board to load, cold-starting Fusion: these take tens of seconds, and a caller that shows "usually about 35s" beats a spinner with no end in sight. ab already streams live progress for long recipes (the web-control demo's `POST /command/stream` heart-beats every step and reports the ACTUAL `tookMs`), but the honest EXPECTATION ("usually ~35s") should come from you, the bridge, because only you know your app.
+
+So, when you can: **declare a rough expected duration for each slow verb**, and ideally **track a rolling actual average** and return it. Concretely:
+- In `bridge.json`, alongside your `timeouts` block, add an optional `verbDurations` map (`{ "kicad_open_symbol_editor": 30, "kicad_open_board": 35, ... }`, seconds) that ab and callers can read to show "usually ~Ns" and to size a timeout honestly.
+- Optionally, keep a rolling average of the last N real runs per verb (a tiny on-disk counter) and surface it in that verb's response (e.g. `timing:{ usuallySec, lastSec, samples }`). A measured number beats a guess, and it self-tunes to the user's machine (a fast SSD vs a slow VM).
+- These are HINTS for UX and timeout-sizing, never a gate: a verb that runs long is not a failure, and ab's per-verb `timeouts` remain the hard budget.
+
+This keeps the "ab renders, the bridge knows its app" boundary: ab does not hardcode "KiCad takes 35s" (that would rot the moment KiCad changes), it just forwards what your bridge reports.
+
+---
+
+## ⭐ SUGGESTED: expose a `<prefix>_state` verb that returns your app's FULL current state (John, 2026-08-14)
+
+A user or AI should be able to ask a bridge, at any moment, "what does the app you control look like RIGHT NOW?" and get back the complete picture, not one guessed window. Today a caller that wants to see KiCad screenshots the first window whose title contains "KiCad" and gets ONE of its two windows; Fusion has a main window plus palettes, so a single title-match grabs a skinny panel. That is wrong, and it is wrong because only the BRIDGE knows the real window set (it tracks its app's parent/child hwnds). A generic title match cannot.
+
+So, when your app has a meaningful visual/logical state: **expose a `<prefix>_state` verb** (e.g. `kicad_state`, `fusion_state`, `blender_state`) that returns the app's current STATE OF THE UNION:
+
+- **A screenshot ARRAY of EVERY window the app owns**: the parent + all child/related windows (project manager + symbol editor + PCB editor + any open dialog), each captured by its real hwnd. Return them as **base64** (`{ shots: [{ title, hwnd, image, width, height }] }`) so a WEB page or AI can render them inline without a file pull. (File paths are fine for the CLI too, but base64 is what makes this usable from the web-control demo and from an AI that cannot reach the desktop's filesystem.)
+- **Plus the logical state** you already know: what document/board/design is open, which editor is focused, is a modal dialog blocking, unsaved-changes flag, current tool, plus whatever else a caller would need to decide the next move.
+
+Why this matters: it turns "drive blind and hope" into "look, then act." An AI can call `<prefix>_state` before and after an action to confirm it landed; a human demo (like the web-control page) can show the app's true state instead of a cropped sub-window. ab already has the generic pieces (`desktop_list_windows` + `desktop_screenshot_base64 {hwnd}`), but the bridge produces the CORRECT set because it owns the window identities, and that is the whole point of the ab-renders / bridge-knows-its-app boundary. Keep it read-only and non-gated (it only observes), and make it cheap enough to poll.
+
+---
+
+## ⭐ EDA bridges: the EIGHT SURFACES contract, `<prefix>_show_*` (John, 2026-08-15)
+
+If your bridge drives an **electronics design tool** (KiCad, Fusion 360, Altium, and whatever comes next), implement these eight verbs. They are not a demo checklist; they are the complete set of things a user has to be able to DO from the Adom Wiki to close the circle from a wiki **component / molecule / board** all the way to the end app the EE actually designs in. A bridge that implements all eight plus `<prefix>_state` gets the web-control demo, the wiki round-trip, and the cross-app parity test for free, with **zero ab-side work**, which is the whole point of keeping ab generic.
+
+| # | Surface | Verb | What it opens |
+|---|---|---|---|
+| 1 | Symbol | `<prefix>_show_symbol` | one schematic symbol in the symbol editor, full pinout |
+| 2 | Footprint | `<prefix>_show_footprint` | one footprint / land pattern, pads + layers |
+| 3 | 3D chip | `<prefix>_show_3d_chip` | the single component's 3D model |
+| 4 | Library | `<prefix>_show_library` | the library browser scoped to one library |
+| 5 | Schematic | `<prefix>_show_schematic` | the design's schematic sheet |
+| 6 | 2D board | `<prefix>_show_2d_board` | the PCB layout editor |
+| 7 | 3D board | `<prefix>_show_3d_board` | the populated board in 3D |
+| 8 | Project | `<prefix>_show_project` | the project/design at its top level |
+
+Rules that make the set usable rather than merely present:
+
+- **`show` is not `open`.** An `open` verb takes a file path or a cloud URN and has app-specific arg shapes; a `show` verb takes the smallest identifier that names the surface (a symbol name plus its library, a file path, nothing at all when the app already has the design loaded) and is responsible for getting the app into that view whatever state it starts from. Having `fusion_open_lbr` does NOT satisfy #4, and having `kicad_open_board` does NOT satisfy #6. Ship the symmetric `show` pair.
+- **They open in the BACKGROUND and are therefore useless without `<prefix>_state`.** A `show` verb that returns `{success:true, activeWorkspace:"..."}` and no image leaves the caller unable to prove anything happened. The state verb above is what renders the result. **Treat the eight verbs and the state verb as ONE deliverable**: six show verbs with no state verb rendered zero surfaces in the demo for a full day, which read as "the feature does not work."
+- **Say when a surface is COLD-capable and when it is WARM-ONLY.** KiCad's 3D chip and 3D board are reliable only once KiCad is already up (kicad-bridge #26). That is a legitimate answer, but it must come back in the verb's own `_hint` so the caller can sequence rather than guess.
+- **A prerequisite miss returns a `_hint` naming the exact next call**, never a bare failure: "needs a library open, call `<prefix>_open_lbr` first" or "run the demo first to generate the sample project."
+- **Zero-setup where you can.** Prefer pointing the demo-facing default at the app's STOCK libraries (KiCad uses `Device` / `Resistor_SMD`) so a fresh box shows something real with nothing staged. Where stock content does not exist, bundle a sample in your zip like Fusion's sample `.lbr`.
+
+Status as of 2026-08-15: **KiCad 0.9.105 implements all eight plus `kicad_state`** (3D chip and 3D board warm-only). **Fusion 1.9.16 implements six** and is missing `fusion_show_library`, `fusion_show_project`, and `fusion_state` (#28). Altium has no bridge yet; when one is written, this table is its spec.
+
+---
+
+## ⭐ REQUIRED: the background/foreground RESPONSE contract - one shape, canonicalized (wiki #82, 2026-08-19)
+
+John's ruling on foreground etiquette (a window opens in the BACKGROUND by default; a foreground move needs a stated human reason and a 3s ab caption first) shipped in kicad 0.9.131 and fusion 1.9.51-52 within a day of each other. The ARGS agreed - `foreground: true` + `foregroundReason` + the caption - and that part is settled. The RESPONSE markers diverged, so a runner had to special-case each bridge. Canonicalizing now, before Altium and the next bridge copy whichever one they happened to read first.
+
+**The rule: what a caller has to branch on is a CONTRACT and gets a stable, non-underscore key. What a caller merely reads is a HINT and keeps the `_` prefix.** That is the whole basis of the choices below, and it is the thing to apply when a future field is added.
+
+| Semantics | CANONICAL | Was |
+|---|---|---|
+| where the window went | **`windowEtiquette: "background" \| "foreground"`** | kicad `openedInBackground: true` |
+| a bare `foreground:true` was refused | **`errorCode: "foreground_reason_required"`** | kicad `_foregroundRefused` |
+| the quietness audit log | **`<prefix>_state.focusEvents[]`** | kicad `kicad_state.focusEvents` (already right) |
+| guidance for the AI | `_hint` (unchanged) | both |
+
+**`windowEtiquette` over `openedInBackground`, because a boolean cannot grow.** The states are already three, not two (background, reason-gated foreground, refused), and a bool forces every later state into a second flag that can contradict the first. An enum also reads correctly on verbs that are not "open" - a raise, a close, a dialog dismissal all have etiquette, and none of them "opened in background". fusion's shape was the more durable one.
+
+**`errorCode` over `_foregroundRefused`, because a runner must be able to BRANCH.** fusion asked for this explicitly and is right: a `_`-prefixed marker is by convention advisory text for the AI, so keying control flow off it makes a doc string load-bearing. `foreground_reason_required` is the stable code; keep the `_hint` alongside it explaining what to pass.
+
+**`focusEvents` is blessed as the canonical name** (kicad's, unchanged) on the `<prefix>_state` verb: an append-only log of every focus change your bridge caused or observed, with a timestamp and a cause. An auditable quietness log is a real assert; "nobody complained" is not. fusion is adding it.
+
+### ⛔ REQUIRED: an envelope is scoped to a STEP, never to an orchestration
+
+fusion's lesson, and it is the one most likely to bite the next bridge, so it is a rule and not a footnote. fusion's tour armed ONE background-suppression envelope sized from an estimate of how long the run would take. Real runs blew through it - cold boots, dialog stalls - the guard expired mid-run, and a window escaped to the foreground. That was the exact foreground leak John caught live.
+
+An estimate cannot bound a step whose duration you do not control. **Re-arm the envelope per step or per operation**, so the guard's lifetime is always shorter than the thing it is guarding, and an overrun costs you a re-arm rather than a leak. This is the same reasoning as the measured-progress rule above: do not let a number you guessed become a thing the system depends on.
+
+**Measured, not theoretical** (fusion, 2026-08-19): a tour armed for ~376s actually ran **485-890s**, and every step after the envelope expired silently reverted to foreground-stealing - it took John's focus while he was working in other threads. The fix is one line per step. **Nesting is refcounted, so re-arming costs nothing** - there is no efficiency argument for the single big envelope, only the illusion of tidiness.
+
+This is REQUIRED rather than recommended for one reason: **the failure is invisible from inside your bridge.** Nothing errors, no log line fires, and you only learn about it when a human notices their window jumped. A rule whose violation is undetectable by its author has to be stated as a rule.
+
+Both existing shapes may be emitted together during a migration window (`windowEtiquette` plus the old key) so a pinned runner does not break, but the OLD keys are deprecated on sight and should be dropped once your consumers are on the new one.
+
+## ⭐ REQUIRED: PRUNE WHAT YOU WRITE - a bridge owns its own scratch directory (kicad-bridge#40, 2026-08-20)
+
+If your bridge writes a file per operation - screenshots, exports, logs, temp
+renders - **you must prune it.** ab will not, and should not: ab's janitor covers
+ab's OWN directories, and a bridge's scratch space is the bridge's. ab deleting
+files out of it would be ab reaching into storage it does not own.
+
+This is a REQUIRED rule rather than advice because the failure is invisible until
+it is large. Measured on one real box: a bridge writing captures per call had
+accumulated **226 files / 37.5 MB**, growing, with nothing pruning it - and it
+went unnoticed for months because nothing errors. Nobody sees a directory that
+merely gets bigger.
+
+**The retention shape that works** (from kicad-bridge 0.9.203, which is a good
+default to copy rather than reinvent):
+
+- an **age cap** (48h is a sane default for evidence captures),
+- a **hard file ceiling** (300) as a backstop for a burst,
+- **oldest-first** eviction over the ceiling - this one is load-bearing, because
+  it guarantees an in-flight capture is never the file you delete,
+- **rate-limited** (once per 10 minutes) so a burst of captures never pays for
+  the sweep,
+- and when you RENAME a directory, **drain the old one and remove it**, or every
+  existing install keeps its orphans forever.
+
+**Write under your own bridge cache**, next to the other bridges, not a
+hand-rolled path:
+
+```
+%LOCALAPPDATA%\Adom Bridge\bridges-cache\<your-bridge>\screenshots\
+```
+
+Two traps worth naming, both hit in the wild:
+
+- **Do not invent a top-level directory** like `C:\tmp\<something>`. It is
+  outside every janitor, invisible to the user's mental model of where apps keep
+  things, and it survives your uninstall.
+- **Check the NAME is current.** A directory created under a retired product name
+  keeps that name propagating long after the rename - and a user auditing their
+  disk finds a folder for an app that no longer exists.
+
+Unit-test the retention rule against a synthetic tree (aged-out removed, fresh
+kept, legacy drained) rather than asserting it - the whole point is that nobody
+will notice when it silently stops working.
+
+## The rest of the SDK library
+
+The SDK is a **skill library**, not one file, so you load only the phase you are in:
+
+| Skill | Load it when |
+|---|---|
+| `adom-bridge-sdk` | orientation (this skill): the boundary, the artifacts, where files live |
+| `adom-bridge-sdk-manifest` | writing or fixing `bridge.json` |
+| `adom-bridge-sdk-runtime` | spawn, runtimes, loopback bind, readiness, LEDs, logging |
+| `adom-bridge-sdk-callback` | calling ab verbs back, caller provenance, window branding |
+| `adom-bridge-sdk-publish` | shipping: the zip + manifest, the skills pkg, discovery, the checklist |
+| `adom-bridge-sdk-audit` | auditing a shipped bridge, staying current, filing issues |
+
+Humans wanting the narrative tour (with screenshots) should read the sub-readme on the
+Adom Bridge page instead: <https://wiki.adom.inc/adom/adom-bridge> - "Build your own bridge".

@@ -0,0 +1,88 @@+---+name: adom-bridge-thesis+description: >-+  The core thesis of Adom Bridge: WHY it exists and what the whole system is for. Read+  this to understand the high-level goal before diving into any verb or feature skill,+  or when a user asks what Adom Bridge is, why they would want it, what problem it+  solves, whether it is only for Adom/Hydrogen users, or how it is safe to let an AI+  control a whole computer. Trigger words: what is adom desktop, why adom desktop,+  adom desktop goal, adom desktop thesis, value proposition, is it safe, do I need+  hydrogen, unleash the AI, full machine access, AI on my PC.+---++# The Adom Bridge thesis: unleash your AI onto your full PC++## The problem++Every AI you use today is locked in a box. A cloud agent lives in a container with no+hands. A chat app can talk about your files but cannot touch them. Even a local AI+assistant sees only what you paste into it. The result is that YOU are the robot: the AI+decides, and you carry out the clicks, the installs, the exports, the file moves.++## The goal++Adom Bridge exists to invert that. It gives your AI access to your full machine, so the+AI assists you in managing and running your entire computer as you, without you having to+do anything manually. The AI breaks out of the container it runs in and onto your real+PC or Mac: your windows, your apps, your files, your shell, your browser, your USB-attached+hardware.++That is the one-line thesis: **Adom Bridge is the unleasher of your full AI.**++Concretely, an AI wired through Adom Bridge can:++- run and manage the whole laptop: launch apps, move files, read logs, restart services,+  take screenshots, drive any window;+- control professional tools like KiCad, Fusion 360, Altium, Blender, or a real signed-in+  browser, through purpose-built bridges;+- do all of it from wherever the AI actually lives: a cloud container over the relay, or+  a local app like Claude Desktop or Codex over loopback.++## Not just for Adom users++Adom Bridge ships with Adom's own Hydrogen environment, but it is deliberately+standalone. A user who never touches Hydrogen still gets the full value: install Adom+Desktop, point any AI at its CLI or API, and that AI can fully drive the PC. If you use+Claude Desktop, Claude Code, Codex, or any other agent on your machine, Adom Bridge is+what gives that agent hands.++## Bridges: Adom Bridge as an operating system for AI++Bridges are how the reach keeps growing. A bridge is a small local server that teaches+Adom Bridge a new namespace of verbs (kicad_, fusion_, browser_, your own). Adom Bridge+behaves like a little operating system around them:++- it provisions its own managed Node and Python runtimes, so a bridge runs without+  touching the user's setup and without a single admin prompt;+- it owns the bridge lifecycle: spawn, stable ports, health, auto-respawn, auto-update+  from the wiki, logs;+- it keeps bridges in a controlled environment: loopback-only binding, a registry, and+  an audit trail.++So building for the AI-driven desktop feels like building an app for an OS, and installing+one is a single verb.++## Full power, full safety++Unleashing an AI onto a whole machine only works if the human stays in charge. That is+the other half of the thesis, and it is why the permission system is a first-class part+of the product, not an afterthought:++- side-effecting commands from a remote AI are gated behind a human approval prompt, and+  the grant is human-only: the AI can ASK for permission but can never grant itself;+- every command is attributed (which AI thread, which container, on whose behalf) and+  visible in the Activity Log;+- Adom Bridge binds to 127.0.0.1 only; nothing off the machine can reach it except+  through the relay the user configured.++Full power and full safety together are the point. Either one alone is easy; the product+is both at once.++## How to use this skill++This skill is the WHY. For the HOW, start with the main `adom-bridge` skill (the verb+surface), `adom-bridge-permissions` (the approval model), `adom-bridge-sdk-guide`+(consuming bridges), `adom-bridge-bridge-sdk` (building one), and `adom-bridge-local-ai`+(driving the PC from a local AI app). When you explain Adom Bridge to a user, lead with+the thesis above, in plain words: it lets your AI out of its box and onto your machine,+with you holding the leash.

@@ -0,0 +1,233 @@+---+name: adom-bridge-verbs+description: The full reference for Adom Bridge's own (ab-core) verbs - every desktop_* / top-level verb the direct API and CLI expose, grouped by category, with a one-line description of what each does and what it takes/returns. Read this to discover what ab can do to a Windows PC (windows, screenshots, input, UI automation, files, shell/WSL, registry/fonts, tunnels, notifications, lifecycle, bridge management, credentials). BRIDGE verbs (kicad_*, fusion_*, pup_*, ...) are NOT here - each bridge ships its own verb skill; this is ab-core only. There is also a live, browsable version at http://127.0.0.1:24680/verbs on any machine running ab.+---++# Adom Bridge core verbs++Every verb below runs via the direct HTTP API - `POST http://127.0.0.1:24680/command {"command":"<verb>","args":{...}}` (loopback; `app` optional/inferred) - or the CLI: `adom-bridge <verb> '<json>'`. On bad/missing args the verb's own `_hint` returns the arg schema. A live, filterable, tabbed version (with a tab per installed bridge) is at **http://127.0.0.1:24680/verbs**.++**Scope:** these are ab-CORE verbs only. BRIDGE verbs (`kicad_*`, `fusion_*`, `pup_*`/`browser_*`, `nbrowser_*`, `blender_*`, ...) are owned + documented by each bridge - install a bridge and read its own skill (or `bridge_list` -> `sync_skills`). The live `/verbs` page shows bridge verbs too (descriptions pulled from each bridge's `describe`).+++## Windows++- **`clear_window_attention`** — Clear a window's taskbar attention highlight (stop the flash + clear the tint) with no net focus change.+- **`close_window`** — Gracefully close a window (WM_CLOSE, so save prompts fire); resolves hwnd|titleContains; optional forceAfterMs kills the OWNING PROCESS only if the window outlives it. Returns measured closed/forced, never asserted.+- **`display`** — Report this desktop's monitor geometry - bounds, work area, per-monitor DPI/scale, primary, and the virtual-screen box; powers display-aware RDP sizing.+- **`enum_windows`** — Enumerate EVERY top-level window (filter by pids/className/includeOffscreen) via Win32 EnumWindows; resolves a window even before it's placed on screen.+- **`find_window`** — Resolve a window's hwnd by titleContains/className in z-order (best=topmost); returns {best, windows[]}.+- **`flash_window`** — Flash a window's taskbar button (FlashWindowEx) as an orange attention cue - until focused or a fixed count; stop:true clears it.+- **`get_foreground`** — Return the OS foreground window {hwnd, pid, title} - check before any z-order/focus change so you never steal a window the user is actively using.+- **`list_monitors`** — Enumerate all monitors with physical + logical (DIP) bounds, work area, DPI, scale, and primary flag; bounds share set_window_bounds' coordinate space.+- **`list_windows`** — List all visible top-level windows with their hwnd, title, position/rect, z-order index (z=0 is topmost), plus owner/pid/image/minimized/maximized/enabled/hung extras and a `degraded` flag when enumeration was partial (never trust a silent empty list).+- **`raise_window`** — Full raise dance for parked/no-activate/minimized windows: clear WS_EX_NOACTIVATE, restore if minimized, foreground-lock bypass; raised is measured, not asserted.+- **`screenshot_window`** — Capture one window by hwnd/titleContains via PrintWindow (works backgrounded/occluded/minimized, no focus steal); returns owned child dialogs as separate images + a coordMap.+- **`set_window_bounds`** — Move + resize a window to exact physical-pixel x/y/w/h (DPI-aware), un-maximizing first; returns the resulting rect.+- **`set_window_identity`** — Make any window present as a named app: set its AppUserModelID + icon + display name (+ relaunch command) so the taskbar, Alt-Tab, hover and pins read your app.+- **`set_window_jumplist`** — Set native jump-list tasks (max 16) on a taskbar button's right-click menu for a registered AppUserModelID; the caller supplies each task, [] clears the list.+- **`set_window_state`** — Set a window's state (maximize|minimize|restore|show|hide|bottom) without necessarily foregrounding; state:bottom atomically sends it behind others in the background.+- **`send_to_bottom`** (v2.1.33, wiki #144) — Put a window at the BOTTOM of the z-order without activating it; atomic check-and-skip when the user is interacting with it (`wasForeground`), `force:true` to demote anyway. Same code path as `set_window_state {state:"bottom"}`.+- **`get_window_identity`** (v2.1.33, wiki #147) — Read back each window's stamped `appId` / relaunch trio from its property store for a batch of `hwnds`; `appId:null` = identity drift, re-stamp with `set_window_identity`. Read-only, ungated.+- **`mesh_status` / `mesh_peers`** (v2.1.40, Adom Mesh P0) — this ab's node identity (ed25519 nodeId), its direct QUIC endpoints and the same-account peers from the Carbon KV directory + LAN mDNS. `--target <name>` tries the mesh first (direct, end-to-end encrypted, no relay) and falls back to the hc relay; a mesh answer carries `route.via = "mesh"`. Relay mode is off in P0 (cross-network reach still needs the hc relay until the Adom negotiation relay lands).+- **`clipboard_set` / `clipboard_get`** (v2.1.33, wiki #145) — MULTI-FORMAT: `clipboard_set {text?, html?, image?: path|base64 PNG}` writes every given format in ONE transaction (CF_UNICODETEXT + CF_HTML + PNG/CF_DIB) so a single paste carries all of them; `clipboard_get {formats:["text","html","image"]}` reads them back (image = PNG imageBase64 + imagePath + size) plus `available`. Gated like the other input verbs. Bridges: stop shipping clipboard helpers.+- **`taskbar`** — Paint glanceable status on any window's taskbar button: progress bar, overlay badge/icon, flash, and thumbnail tooltip/clip (ITaskbarList3). v2.1.22: a progress bar carries a fail-safe TTL (default 10 min, refreshed by every tick; `progress.ttlMs` overrides, 0 = never) so a dead painter cannot leave a frozen bar, and `{action:"list"}` enumerates everything ab currently paints so a restarted painter can sweep its own leftovers.+- **`ui_window`** — Window ops via UIA WindowPattern/TransformPattern: minimize|maximize|restore|close, or move{x,y}/resize{w,h}.+- **`wait_for_window`** — Block (bounded) until a window matching titleContains/className/pid APPEARS - or with state:"absent" until it GOES AWAY (dialog dismissed, app exited). The honest alternative to sleep-and-rescreenshot loops.+- **`window_hide`** — Hide ab's own main window; the app keeps running in the background (window_show brings it back).+- **`window_show`** — Show + focus ab's main window (CLI: desktop_window_show); per-call panel intent for the Hydrogen companion roll-up. Fired by ah's tray 'Open Adom Bridge'.++## Capture & recording++- **Whole-desktop recording is NATIVE as of v2.1.35 (wiki #143):** `record_start {monitor?, fps?, audio?, maxDurationMs?}` captures one monitor with Windows Graphics Capture plus the system audio mix (WASAPI loopback) into an H.264/AAC MP4, no browser, no picker; a persistent caption shows the user the take is running; `record_stop` finalizes, `record_status` (no id = all) and `record_list` (finished files) round it out; `record_window_*` is the single-window spelling. The response names the encoder Media Foundation chose (`encoder`, `hardwareEncoder` = NVENC / Quick Sync / AMF) and, as of v2.1.51 (wiki #149), the pipeline: `gpuZeroCopy:true` / `framePath:"gpu"` means frames stayed on the GPU end to end (WGC surface, a pooled DXGI sample, the hardware encoder through a shared D3D11 device manager: no CPU map, no memcpy, no upload); `framePath:"cpu"` is the automatic fallback when the box or driver refuses the D3D-aware chain (`gpu:false` forces it); `bitrate` (bits/s) overrides the resolution-derived target. `droppedFrames` on stop/status counts ticks the encoder was too far behind to take a pooled sample. `recorder_open/close` are retired. Chrome screen-share recording (OS picker consent, WebM) is pup's `pup_screen_record_*`, kept on purpose as a different tool.+- **`record_list`** — List completed desktop recording .webm files on disk with their sidecar metadata. (pup-served; see above)+- **`record_start`** — Start a whole-desktop recording (every on-screen pixel) via Chrome getDisplayMedia to .webm; opens the HUD if needed. Reason required.+- **`record_status`** — Report the desktop recorder HUD state and any active clip.+- **`record_stop`** — Stop the active whole-desktop clip and finalize the .webm; the HUD stays open in Ready state for the next clip.+- **`record_window_start`** — Start a native single-window recording (Windows Graphics Capture + Media Foundation) to MP4 - no picker/banner, background-capturable; target by hwnd or titleContains.+- **`record_window_status`** — Report the status of a WGC single-window recording.+- **`record_window_stop`** — Finalize a WGC single-window recording: stop capture, write the MP4 moov atom, return the on-disk path.+- **`recorder_close`** — Close the desktop recorder HUD, ending the session (auto-stops any active clip first).+- **`recorder_open`** — Open the whole-desktop recorder HUD (always-on-top window) without starting a clip; reason required.+- **`screenshot_screen`** — Capture the entire desktop (all monitors) as lossless PNG - only shows what's visually on top; prefer screenshot_window for a specific backgrounded app.++## Input & UI automation++- **`ad_scroll`** — Scroll ab's OWN window panels (bridges|activity|connections) to top/bottom or by a delta, returning post-scroll geometry so you can page and screenshot below the fold.+- **`caption`** — Show a large always-on-top, click-through text overlay on the user's desktop for narration / screen-share labels / status banners (Win32 layered window).+- **`click`** — Real OS left-click at {x,y} (screen px, image px with `space:image`+`shotId`, or a fraction of a window with {hwnd|titleContains, fx, fy} - 0..1 of the client area, DPI-proof). GLOBAL OS input via SendInput - a real pointer move at the screen level, indistinguishable from the human's own mouse, so it drives ANY window including elevated/admin apps and custom-drawn UIs (CAD, games, installers) that UIA and CDP cannot reach. The glowing Adom cursor is glided there first BY DEFAULT so the user sees WHO is driving; pass label to narrate it, or cursor:false to suppress. Requires a `reason` from a relay caller (rendered on screen).+- **`cursor`** — **VISUAL ONLY, does NOT move the mouse** (use `hover`/`move`/`click` for that). Shows/glides/hides the glowing teal Adom cursor overlay - the Adom mark + a narration label - so the human sees the Adom ecosystem is driving. Auto-hides.+- **`demo_panel`** — Floaty glass BACK / PLAY-PAUSE / NEXT / MUTE transport the USER controls during a guided demo (plus a corner X = a `stop` event). `show` creates/updates it (reason required; same-id shows persist omitted fields), `poll` drains the user's presses between beats (honor paused / next / back / mute / stop / idle_hide; `muted` rides every reply - silence your narration audio while true), `hide` ends the show; `press` (reason required) injects a synthetic button press through the real push path (tagged synthetic:true) for ralph-testing your wiring. A LOCAL caller may pass `eventCallbackUrl` (loopback http) for an instant POST per press; the 10-min idle auto-hide announces itself as `idle_hide` on both wires. A press never executes anything - it only queues an event for you. Full recipe (panel + captions + cursor pacing loop): the **adom-bridge-demo-kit** skill.+- **`find_control`** — Read-only UIA discovery: find a control by name/automationId/role under a window and report whether it's background-actionable plus its screen rect.+- **`find_controls`** — READ-ONLY: return ALL UIA controls matching a selector as an array with nth indices.+- **`mouse_move`** / **`mouse_click`** / **`mouse_double_click`** / **`mouse_right_click`** — aliases of `hover` / `click` / `double_click` / `right_click`, named so the verbs that move the mouse are findable by searching "mouse". Same behaviour, same gating.+- **`hover`** — **MOVE THE MOUSE** to {x,y} without clicking (reveals tooltips/hover states). Alias: `move`. GLOBAL OS input via SendInput - a real pointer move at the screen level, indistinguishable from the human's own mouse, so it drives ANY window including elevated/admin apps and custom-drawn UIs (CAD, games, installers) that UIA and CDP cannot reach. The glowing Adom cursor is glided there first BY DEFAULT so the user sees WHO is driving; pass label to narrate it, or cursor:false to suppress. Requires a `reason` from a relay caller (rendered on screen).+- **`navigate`** — Focus-neutrally open a URL in a browser window's active tab via UIA (SetValue the omnibox, Enter, restore prior foreground); returns an honest navigated signal.+- **`press_key`** — Send keyboard chords/shortcuts via SendInput (real keys reach chrome:// + native dialogs). Alias: send_keys.+- **`show_ui`** — Stage an in-window ab UI element and wait ~350ms for render so it can be captured via screenshot_window.+- **`type`** — Type a literal Unicode string into the focused control via SendInput (any keyboard layout); optional window/hwnd to focus first. Works on chrome:// + native dialogs.+- **`ui_capabilities`** — READ-ONLY: the foreground-hint table for every UIA verb - consult before acting to know whether a call steals the screen.+- **`ui_click`** — Background UIA InvokePattern click of a control by accessible name - no foreground/focus steal/cursor move; falls back to a foregrounding SendInput click if no pattern.+- **`ui_events`** — Drain buffered UIA events past sinceSeq (poll cursor, like bridge_log_read) and list active watches. READ-ONLY.+- **`ui_expand`** — Expand/collapse a tree node or combobox via UIA ExpandCollapsePattern (background, no focus steal).+- **`ui_focus`** — SetFocus to a UIA control; this often raises the window - the measured foreground block reports whether it did.+- **`ui_from_point`** — READ-ONLY: identify the UIA control under a pixel (screen px, or image px via space:image+shotId).+- **`ui_get`** — READ-ONLY: read a control's current value/state - Value, ToggleState, RangeValue, selected, ExpandState - whichever apply.+- **`ui_grid_get`** — READ-ONLY: read UIA GridPattern dimensions (rowCount/columnCount) and a {row,col} cell's info.+- **`ui_scroll`** — Scroll a region via UIA ScrollPattern {dir}, or bring an item into view via ScrollItemPattern (pass no dir).+- **`ui_select`** — Select a list item / tab / radio via UIA SelectionItemPattern (background).+- **`ui_selftest`** — Write the UIA capability table to ~/.adom/ui-capabilities.json; with {confirm,window} it empirically measures foreground by toggling a real control and restoring it.+- **`ui_set`** — Background UIA ValuePattern SetValue on a control by name (no foreground); optional submit commits with Enter, then restores the prior foreground window.+- **`ui_set_range`** — Set a slider/spinner value via UIA RangeValuePattern (background).+- **`ui_text`** — READ-ONLY: read the text of a document/edit/text control via UIA TextPattern.+- **`ui_toggle`** — Toggle a checkbox/switch via UIA TogglePattern in the background, or set it to {state:true|false}.+- **`ui_tree`** — READ-ONLY: dump the UI Automation accessibility subtree under a window (or a subtree scope) - see the whole controllable surface, no name guessing.+- **`ui_unwatch`** — Stop one UIA watch or all of them; the watcher thread tears its handler down within ~150ms.+- **`ui_watch`** — Subscribe to a UIA event stream and get a watchId; events flow to the activity-log and a ring buffer drained with ui_events. READ-ONLY.++## Files++- **`delete_file`** — Delete a file or directory in ab's context with typed args and no shell quoting; idempotent. Absolute path required.+- **`list_dir`** — List a directory as structured entries (name/isDir/size), dirs first then alphabetical; absolute path, no shell quoting.+- **`list_files`** — List one directory's files matching a shell-glob, optionally only those modified after a timestamp; non-recursive, newest-first.+- **`open_folder`** — Open a file or folder in Windows Explorer.+- **`open_url`** — Open a URL in the user's real default OS browser (their logged-in Edge/Chrome/Firefox), not Puppeteer - for pages a human must interact with.+- **`pull_file`** — Pull files from the desktop back to the container, streamed as 1 MiB binary WS frames (no practical size limit).+- **`read_file`** — Read a file in ab's own context (expands %VARS%/~, handles wcifs paths), replacing type/Get-Content quoting.+- **`send_files`** — Send files from the container to the desktop - lands in the configured receive dir (Downloads) or an absolute dest; handles multi-MB to hundreds-of-MB files.+- **`watch_files`** — Block until a file matching a glob appears in a directory (mtime > since) or timeoutMs elapses; polls the filesystem, no shell.+- **`write_file`** — Write a file in ab's context (parent dirs created), replacing Set-Content/echo quoting; retrieve with pull_file or run with run_script.++## Shell / WSL / process++- **`find_exe`** — Resolve an executable's absolute path without launching - searches absolute path, webdeploy version globs, Start Menu .lnk targets, then PATH.+- **`launch`** — Launch an executable by absolute path or bare name, verifying it exists first (avoids the Windows 'cannot find' dialog). Args/cwd/detached; returns pid, resolvedPath.+- **`launch_process`** — Launch a detached fire-and-forget process with an args ARRAY (no shell quoting); env/cwd/window overrides, plus breakawayFromJob/detached flags so the child survives its parent's job-object teardown (installers, updaters). Returns pid immediately; stop with process_kill.+- **`launch_rdp_client`** — Launch mstsc against an open RDP tunnel's local port with display-aware sizing; first verifies 127.0.0.1:<localPort> is listening, refusing a dead port.+- **`process_kill`** — Kill a process by pid (surgical, preferred) or image name (kills all with that name), force + child tree. Returns exitCode, stdout, stderr.+- **`process_list`** — List processes with reliable command lines via CIM (pid/name/parent/handles/memory); optional name or pid filter. Replaces tasklist/Get-Process.+- **`relaunch_self`** — Dev self-restart: spawns the visible ad-relauncher (HOST context) to redeploy from the build tree, relaunch, and verify. Poll relauncher_status.+- **`relauncher_status`** — Query the ad-relauncher's state JSON: overall status, current/per-step progress, stopping/launching version info, HOST/SANDBOX context, and log tail.+- **`request_shell_approval`** — Surface a human-clickable shell-approval prompt (in-window dialog + toast + foreground ab). The AI's lever to trigger the human grant - it never grants itself.+- **`run_script`** — Execute a base64 (or plain-body) script via cmd/powershell/bash/node/python with zero quote mangling. Returns stdout, stderr, exitCode, timedOut. Tier-2 gated.+- **`set_shell_auto_approve`** — Set or revoke the shell auto-approve grant. A GRANT from a relay caller is refused (human_only) and surfaces the human prompt; a REVOKE (duration_secs:0) is allowed for any caller.+- **`shell_execute`** — Run a shell command on the desktop (Windows cmd /c, else sh -c); Tier-2 gated escape hatch. Args command/cwd/timeoutSeconds -> stdout, stderr, exitCode.+- **`wsl_exec`** — Run a base64 bash script inside a WSL distro via canonical wsl -d <distro> -u <user>, auto UTF-16 decode. Args distro/user/scriptB64. Tier-2 gated.+- **`wsl_exec_async`** — Async held-session WSL exec for multi-minute work (golden-image bakes): spawns detached, streams to a log, returns a jobId immediately. Poll wsl_job_status. Tier-2 gated.+- **`wsl_export`** — Export a named WSL distro to a .tar (or .vhdx with vhd:true); long op returns a jobId - poll wsl_job_status. Tier-2 gated.+- **`wsl_import`** — Import a tarball as a NEW WSL2 distro (wsl --import); long op returns a jobId - poll wsl_job_status. Tier-2 gated.+- **`wsl_job_status`** — Poll an async WSL job (exec/import/export/unregister): running, done, exitCode, elapsedMs, outputTail. Read-only.+- **`wsl_list`** — List installed WSL distros (name, state, version, default) via a fast registry read (no LxssManager wake). Read-only.+- **`wsl_recover`** — Recover a wedged WSL by reaping orphaned/hung wsl.exe clients. Dry-run by default; {confirm:true} reaps; spares distros with child processes.+- **`wsl_unregister`** — Unregister (DELETE) one named WSL distro; long op returns a jobId. Irreversible; refuses the live Adom-Workspace. Tier-2 gated.++## Registry & fonts++- **`font_ensure_brand`** — Idempotently ensure the Adom brand fonts (Satoshi, Familjen Grotesk, JetBrains Mono) are installed per-user, fetching any missing. Tier-2 gated for relay callers.+- **`font_install`** — Install a .ttf/.otf font per-user with NO admin (from a local path or URL): copies to the user Fonts dir, writes HKCU, broadcasts WM_FONTCHANGE. Refuses .woff2.+- **`font_list`** — List installed Windows font families (per-user AND machine) from the HKCU/HKLM Fonts registry; read-only, ungated, optional name-substring filter.+- **`font_uninstall`** — Remove a PER-USER installed font (never touches machine fonts): drops the HKCU value, RemoveFontResourceW, deletes the file, broadcasts WM_FONTCHANGE.+- **`registry_delete`** — Delete a registry value (name set) or an entire key + subtree (name omitted). Tier-2 gated.+- **`registry_get`** — Read a Windows registry value: hive + plain (unescaped) key + optional value name. Returns exists, type, value.+- **`registry_set`** — Set a Windows registry value, creating the key path (REG_SZ/REG_DWORD). Tier-2 gated; HKLM needs elevation.++## Network / tunnels / relay++- **`connect_all`** — Connect every enabled relay server that isn't already connected (mirrors the tray 'Connect All'); returns spawned vs already-connected counts.+- **`disconnect_all`** — Close all live relay WS connections; config entries stay and can be reconnected with connect_all.+- **`kick_all`** — Force-disconnect all relay WebSocket clients (they auto-reconnect in ~5s). Use when connections are stale or duplicated.+- **`net_stats`** — TCP/socket stats: totals, listening/established/timeWait, ephemeral-port range + headroom, and per-pid socket counts (the signal ab's spawn-headroom gate uses).+- **`rdp`** — Alias for 'tunnel rdp': open a verified tunnel then launch mstsc on the same target, sized to the laptop's real screen. Args to/target/size/monitor.+- **`server_add`** — Register/upsert a relay server connection by name (url, optional authToken, autoConnect); persists to config.json. Equivalent to the GUI's Quick Add.+- **`server_list`** — List persisted relay servers with live connection status (connected, status, clientCount).+- **`server_remove`** — Disconnect (if connected) and delete a relay server entry by name. Idempotent.+- **`server_sync`** — Re-read the signed-in user's cloud profile server list (cloud-wins merge) and connect now - propagates a new or token-rotated relay to a live desktop.+- **`tunnel`** — Grouped TCP-over-relay tunneling (open|close|list|check|rdp): binds a 127.0.0.1 listener on a desktop while the relay dials the upstream; both legs verified. Args to/target/local.+- **`tunnel_check`** — Alias for 'tunnel check': on-demand per-leg health for one tunnel - ab probes its listener, relay probes upstream, names the failed leg.+- **`tunnel_close`** — Alias for 'tunnel close': tear down a tunnel or one conn; select by tunnelId, local port, or all:true (reaps leaks).+- **`tunnel_list`** — Alias for 'tunnel list': live tunnels with relay + desktop reconciliation, flagging leaked rows.+- **`tunnel_open`** — Alias for 'tunnel open': bind a verified local TCP listener to an upstream host:port over the relay. Returns tunnelId, localPort.++## Notifications++- **`notify_dismiss`** — Programmatically clear a sticky toast by its correlation id - removes it from the notification center and clears any un-consumed response; best-effort.+- **`notify_events`** — PUSH-drain every toast-button click since sinceSeq in ONE call (durable, cross-process cursor); poll this instead of notify_response per-id.+- **`notify_response`** — Poll which toast button the user clicked, by correlation id: {pending:true} until they click, then {pending:false, action}. Consumed on read.+- **`notify_user`** — Send a native branded Windows toast (title/body/level/buttons/progress); optionally focus a window on click, or wait:true to block and return the user's choice.++## Lifecycle / update / settings++- **`apply_update`** — Apply the already-staged update and relaunch ab (programmatic 'Install now'); respects busy and only runs ab's own SHA-verified signed release.+- **`bridge_check_updates`** — Read-only: for each installed bridge report current vs latest wiki version and updateAvailable. Downloads nothing; run before refresh_bridges.+- **`embedded_enter`** — Switch ab into ah-embedded mode at runtime (runtime-adopt): on ah's death ab reverts to standalone rather than exiting. Idempotent.+- **`embedded_release`** — Gracefully leave embedded mode - always reverts ab to standalone (tray restored, marker cleared); never exits the process (use shutdown to exit).+- **`embedded_status`** — Report whether ah is managing this ab: embedded flag, owner, source, enteredVia, pending relay url/name, start-hidden, and marker path.+- **`logout`** — Clear ab's cached Adom Cloud session (~/.adom/session.json) so the footer stops showing a stale email; equivalent to the GUI Sign-out.+- **`request_update_approval`** — Surface the footer 'Update available - Install now / Later' banner + foreground ab on an attended box. Does not apply the update.+- **`restart`** — Production-safe in-place restart of ab (no redeploy): reuses ad-relauncher with source=dest=the deployed exe. Poll relauncher_status until done_ok.+- **`restart_bridge`** — Kill + respawn a bridge in one call (reaps its tracked PIDs plus any orphan on its runtime port), respawning from the current cache on the same stable port.+- **`revoke_approvals`** — Clear all shell auto-approve grants and deny any pending approval requests.+- **`settings_get`** — Read ab's durable user settings (launch_on_boot, update_mode, prewarm_*, file_receive_directory, etc.) plus whether the launch-on-boot OS artifact exists. Read-only.+- **`settings_set`** — Change whitelisted ab settings (launch_on_boot applies the Startup artifact immediately); the sanctioned way for ah to forward setting changes. Tier-2 gated for relay callers.+- **`shutdown`** — Graceful ab exit - stop bridges (kicad/fusion/puppeteer) then exit ~500ms after replying. Used by ah's tray Quit.+- **`update_check`** — Force the target to check the wiki manifest now and, if newer, download + SHA-verify (stage) it in the background. Returns the update_status shape.+- **`update_demo`** — Test/demo verb: safely show any update-tier PRESENTATION (normal banner / high toast / emergency countdown dry-run) for docs/screenshots; nothing installs.+- **`update_demo_emergency`** — Test/demo verb: run the REAL emergency forced-update chain (manifest resolve, signed download+SHA, Authenticode gate, countdown) then DRY-RUN the apply - never restarts.+- **`update_set_mode`** — Set the target's auto-update policy: auto (apply on the 4h/launch poll), prompt (banner, default), or off. Persists.+- **`update_status`** — Read the app self-update state: currentVersion, latestVersion, updateAvailable/Ready, state, updateMode, and priority/forced. Read-only.++## Bridge management++- **`bridge_detail`** — Alias for bridge_info: rich detail for one bridge (log tail, resolved ports, license, full verb list, processLive).+- **`bridge_info`** — Rich detail for one bridge (alias bridge_detail): everything bridge_list returns plus logTail, resolved ports, license, full verb list, manifestUrl, processLive.+- **`bridge_install`** — Install a bridge from a wiki manifest URL: download + SHA-verify + unzip the runtime into the cache and rescan; persists the URL for auto-updates. Returns skillPkg/installSkill.+- **`bridge_kill`** — Kill all of one bridge's tracked processes (image-verified reap); it respawns on the next routed verb (or via the supervisor) on the same stable port.+- **`bridge_dev_mode`** — Freeze/unfreeze ONE bridge against ALL automatic updates (`{name, on}` writes a .dev-pin marker) so a developer's local changes in its cache are never clobbered by the sweep/on-launch sync/auto-update/refresh. `bridge_list` shows `devPinned:true`; the GUI card shows an amber "dev pin" badge with one-click Unpin. NEVER remove someone else's dev pin to "get the latest" without asking - the pin means a human is mid-development.+- **`bridge_list`** — List every installed bridge (name, version, source, ports, verbPrefixes, paused, livePids, devPinned) plus update-diagnosis fields (manifestSource, tier, lastSyncDetail with the probed tier + outcome, versionDrift) and each bridge's skillPkg/installSkill for skill discovery.+- **`bridge_log_read`** — Read/stream a bridge's log: initial tailLines, or new bytes since sinceOffset (tail -f). Returns log (bridge stdout) + adLifecycle (ab's spawn/reap audit) separately.+- **`bridge_pause`** — Pause a bridge: calls to its verb prefixes fail with bridge_paused until bridge_resume. Routing flag only - the server process is not killed.+- **`bridge_readiness`** — Read-only readiness probe across every bridge - never spawns or installs. Reports host-app installed, runtime ready, and state (ready/warming/needs-runtime/no-app).+- **`bridge_resume`** — Resume a paused bridge - flip the routing flag back on. Inverse of bridge_pause.+- **`bridge_start_all`** — Re-enable bridge spawning after bridge_stop_all/--safe-mode: flip the kill-switch ON; bridges lazy-spawn on the next routed verb.+- **`bridge_stop_all`** — Global kill-switch: disable ALL bridge spawning AND stop the running bundled bridges (kicad/fusion/browser); the one-call cure for a runaway bridge.+- **`bridge_uninstall`** — Remove a bridge from the cache (bundled ones revert to the bundled fallback, third-party fully removed); does NOT kill the running server process.+- **`install_kicad`** — Unattended KiCad install via winget (~700MB, 2-5 min); a fixed-command verb (no shell-approval). Call when kicad_list_versions returns kicad_not_installed.+- **`install_node`** — Unattended Node.js LTS install via winget; call when a browser_* verb returns node_not_found, then retry - the bridge reads node.exe from the registry, no restart.+- **`refresh_bridges`** — Force an immediate wiki sync of the bridge cache (all, or {name}); applies on-disk updates and auto-restarts a running bridge to pick up new code.+- **`refresh_heroes`** — Force-refresh ONLY the bridge ART cache (hero images + wiki meta); does not sync bridge code (use refresh_bridges).+- **`runtimes`** — Read-only status of the ab-managed portable Node/Python runtimes bridges share (state, version, source system|cache, exe). No-UAC provisioning.+- **`sync_skills`** — Reconcile this container's ~/.claude/skills with the connected desktop's bridges: pkg-install each bridge's skillPkg. Idempotent; also auto-runs daily.++## Credentials++- **`decrypt_browser_credentials`** — Decrypt the user's own saved Chrome/Edge/Brave passwords+cookies (incl. App-Bound Encryption) via an elevated helper; LOCAL callers only (a relay caller is refused `relay_forbidden`). **Requires `reason`** — the user reads it on screen while deciding. Gated by an on-screen caption naming the asking thread + what it wants, an in-ab consent dialog, and the Windows UAC prompt.++## Wiki / misc++- **`activity_filter`** — Set the human's GUI activity-log filter by bridge name and/or free-text substring; view-only, does not change what verbs the AI can call.+- **`set_project_watch`** — Enable/disable watching a KiCad project directory: on file change ab base64-syncs the project files to connected relay servers.+- **`trigger_project_watch`** — Force an immediate re-sync of the watched KiCad project's files to connected relay servers (no waiting for the poll).+- **`wiki_exec`** — Run the bundled adom-wiki CLI on the user's PC (repo/pkg/release/discussion ops) with the signed-in session token injected. Args argv/cwd/timeoutSec. Tier-2 gated.++## Other++- **`bring_to_front`** — Bring a window (by hwnd or titleContains) to the foreground, optionally maximizing or restoring it.+- **`commands`** — Return the full CLI help-map: every verb grouped by namespace with description/args/returns (aliases: list_commands, help).+- **`double_click`** — Real OS double-click at {x,y} via SendInput; optional focus-first window/hwnd.+- **`janitor`** — CLI-local screenshot-cache janitor: {sub:status} lists managed dirs/sizes/policy, {sub:run} forces a sweep now. Keeps the pull cache bounded.+- **`list_browsers`** — Catalog every installed native browser plus its profiles and signed-in account emails; the static inventory for picking browser+profile before open_url.+- **`ping`** — Round-trip connectivity test (5s timeout); optional message echoed back. Run first to verify the desktop connection.+- **`register_app_identity`** — Register an AppUserModelID with Windows (HKCU key + optional Start Menu shortcut) so it resolves to a name + icon; call once per install. shortcut:false = registry-only (nothing in the Start Menu); its known cost is that the taskbar jump list flashes on the first right-click and stays on the second (wiki #155, measured). `anchor:true` opts in to a small visible anchor .lnk inside one Start Menu subfolder (`anchorFolder`, default "Adom Bridge") that fixes it, at the price of a Start Menu entry (default off since 2.1.49: a clean Start Menu wins).+- **`right_click`** — Real OS right-click at {x,y} via SendInput to open context menus; optional focus-first window/hwnd.+- **`status`** — Query connected clients, capabilities, and app install/run status (kicad/fusion/browser), plus WSL wedge and bridge-update health.+- **`targets`** — List the Adom Bridges connected to this relay (name, hostname, version, os) so you can address one with --target <name> or --target all.+- **`timeouts`** — The per-verb HTTP timeout registry: defaults plus the long verbs mapped to their budget and the status-verb to poll on a timeout.+- **`responseMode`** on ANY verb (2.1.50, wiki #154) — `"job"`: the call returns `{jobId, state, cursor}` at once and the verb runs under that job; a gated verb PARKS on `waiting_for_approval` and resumes once on a real human decision (any surface, any mesh box) instead of failing with needs_approval. `"stream"`: the same job followed by the CLI, one JSON line per lifecycle event, result last, bounded by `streamTimeoutSeconds` (detaching never cancels).+- **`job_status`** / **`job_events`** / **`job_cancel`** (2.1.50, wiki #154) — snapshot, cursor-based event replay with long-poll (`waitMs`), and withdrawal of a parked job.+- **`app_instances`** / **`app_instance`** (2.1.50, wiki #126) — the instance-registry primitive for multi-instance apps: every running instance of an exe with a STABLE key (image:pid:start time), its windows (hwnd/title/hung), command line and a per-instance scratchDir; `app_instance` resolves exactly one by key | pid | hwnd | titleContains or refuses with `ambiguous_instance` + candidates.+- **`bridge_audit`** (2.1.50, wiki #124) — the command audit: every verb ab ran (who: thread/container/delegate, why: reason, origin relay|local|bridge, durationMs, success/errorCode), filterable by bridge/thread/verb/since/failuresOnly/installGrantOnly; in-memory ring + `~/.adom/audit/commands.jsonl`. Also returns the bridge's own persistent events.+- **`bridge_event_log`** (2.1.50, wiki #124) — a bridge appends its own operational event (dialog reap, watchdog firing, instance change) to `~/.adom/audit/bridges/<bridge>.jsonl`, which outlives its respawn; read back with `bridge_audit {bridge}`.+- **`relay_boot_hook`** (2.1.50, wiki #45; CLI-local) — `status | install | remove` a cron `@reboot` line that restarts `adom-bridge serve --supervise` after a container reboot.+- **`desktop_taskbar` thumbbar** (2.1.50, wiki #38) — `thumbbar:[{id?, icon, tooltip?, enabled?, hidden?}]` (max 7): an icon-only status strip under the hover preview; slots are added once per window and only their icons/tooltips/flags change afterwards.+- **`unregister_app_identity`** — Remove an app-identity registration: delete its HKCU AppUserModelId key and any Start Menu shortcut carrying that AUMID (root and the anchor folder; pass `anchorFolder` if you named one; an emptied folder is removed). Idempotent.+- **`user_idle_ms`** — Milliseconds since the last system-wide keyboard/mouse input (GetLastInputInfo) - yield intrusive work while the user is active.

@@ -0,0 +1,678 @@+---+name: adom-bridge-web-control-test+description: How to run - and how to BELIEVE - a web-control test of the KiCad/Fusion library verbs across a batch of wiki components. Covers the four-artifact evidence contract every library import owes (symbol, footprint, 3D chip, ganged view), the mandatory per-image content check, the five known false-success modes that make a green flag lie (stale window, blank workspace, placeholder 3D, screensaver, name mismatch), and the rule that the run is driven from the web-control page in pup so the UI itself is part of the evidence. Read this BEFORE running any "test N components through web control" request. Trigger words: web control test, library matrix, run the library verb on N parts, evidence images per component, kicad_show_library, fusion_show_library, prove the import worked.+---++# Web-control library test — the procedure, and the reasons for it++Every clause here was written after a run reported success and the images said+otherwise. Nothing in it is precautionary.++## The one-sentence rule++**A flag is a claim; an image is evidence; only a *read* image is proof.**+`success: true` from a library verb has been wrong in five distinct ways+(below). Never report a part as passing until you have looked at its picture and+named what you saw.++---++## The mission — why this exists++This is not a smoke test you run once and tick off. It is a **standing+edge-case-hunting campaign** with one goal: *when any Adom user imports a Fusion+or KiCad library — or a symbol, a footprint, a 3D chip, a schematic, a board, a+project — it works perfectly for them.*++The way you get there is to **run these imports over and over, across many parts+and every surface, and find the crazy scenarios HERE — first — before a real+user does.** Every scenario you find gets fixed in the right place (ab core, the+kicad/fusion bridge, the harness, or this skill) and then re-run to confirm.+Running the same test repeatedly is not waste; each run either adds a scenario to+the catalog (§7) or confirms a fix. The catalog is the point — it is how+repetition compounds into coverage.++So a run is never "done" at 10/10 green. A run is done when you have either+**found a new edge case** (→ §8, route it to a fix) or **confirmed the known ones+still pass**. Both outcomes are the deliverable; a run that found nothing new and+a run that found a bug are both successful runs.++---++## ⭐ The NORTH STAR — every import begins with a PRE-FLIGHT PLAN and runs against a REAL progress bar (John, 2026-08-26)++This is the most important UX goal of the whole campaign, and it is easy to lose+sight of while chasing individual bugs. **A library import must never fire blind+verbs that fail one after another.** It must first *gather requirements*, show the+user a *plan* with a time estimate, and then run against a *real measured progress+bar*.++The failure this replaces (real, John on AdomLapper with Fusion closed): the demo+fired `fusion_bind_library_3d` → `fusion_show_symbol` → `footprint` → `3d`, and+**every one failed with "Fusion 360 is installed but not running"** — no+detection, no auto-open, no ETA, no bar. A user cannot tell "Fusion is just+closed, opening it" from "this is broken."++**What must happen instead — pre-flight, then a measured run:**++1. **Detect Fusion's state.** If it is not running, **auto-open it** and SAY so:+   *"Fusion isn't open — opening it (usually ~54 s)."* Fold that into the ETA.+   Never let "the app was merely closed" become four silent failures.+2. **Enumerate the files to stage** (`.lbr` + `.step`), their **sizes**, and an+   **estimated transfer time** from the user's typical download speed.+3. **Enumerate the steps** with a **per-step ETA from past-run history** — e.g.+   create symbol, create footprint, import 3D to Fusion cloud, show ganged view+   with refreshed 3D icon.+4. **Show the plan**: *"Ready to create Fusion library. ~2 min 46 s on average+   based on past runs. (Had Fusion already been open, ~49 s.)"* + the step list.+5. **Run with a real progress bar** advancing across the planned steps, streaming+   each artifact as captured (symbol → footprint → 3D chip → ganged, per the+   evidence contract), `confidence:"measured"` where history exists, `blockedBy`+   when a step waits on a human (Autodesk sign-in).++**Division of labor — ~80 % is the BRIDGE's job, ~20 % the orchestrator's (ab /+the web page):**++- **Bridge:** is Fusion running? auto-open it + report the launch ETA; the step+  list + **per-step ETAs from its own past-run telemetry** (only the bridge has+  run these steps before); the measured-progress stream; a clear async-completion+  signal; all four artifacts including the dedicated 3D chip.+- **Orchestrator:** local file sizes + transfer-time estimate on THIS machine;+  rendering the plan summary + the progress-bar UI.++**The contract to demand from the bridge** is a pre-flight verb, e.g.+`fusion_plan_library_import { lbrPath, stepPath }` → `{ fusionRunning, willOpenFusion,+openEtaSec, steps:[{key,etaSec}], totalEtaSec, totalEtaIfFusionOpenSec }`, then the+import emits measured progress against that plan.++Filed as **fusion-bridge #64** (this contract), on top of **#60** (4-artifact+bundle + streamed + measured progress), **#62** (capture false-pass + async+completion signal), **#63** (the dedicated 3D-chip view). When you run an import+and it does NOT begin with a plan + a bar, that is itself the finding — route it,+do not just work around it.++---++## 1. The evidence contract++Importing a component library is not one thing succeeding. It is four, and the+test owes the human all four **per part**:++| # | artifact | what proves it |+|---|---|---|+| 1 | **symbol** | schematic glyph drawn on the canvas, with the part's own geometry |+| 2 | **footprint** | pad layout for that package |+| 3 | **3D chip** | the part's **own** STEP body — not a generic block |+| 4 | **ganged view** (Fusion) | the one window showing 1–3 together |++The web-control page already names this contract: its library button reads+**"Library (<part>) — proves all 3"**. If your evidence does not show all of+them, the test failed *or the bridge failed* — decide which and say so. It is+never "close enough".++## 1a. The library verb alone is NOT the library flow++**Read this before concluding a bridge is broken.** I filed two bug reports that+were my own error, both from the same mistake: calling `kicad_show_library` /+`fusion_show_library` bare and treating the result as the library flow.++The real flow — what the web-control page does, and what you must replicate if+you drive the verbs directly:++| step | why |+|---|---|+| **Fusion: `fusion_bind_library_3d {libraryPath, stepPath}` FIRST** | without it the library has no package3d and Fusion renders the grey Placeholder slab **by design**. This is not a bug. Skipping it manufactures §3.4. |+| then the `*_show_library` open | |+| then `show_symbol` / `show_footprint` / the 3D surface | one capture each — this is what produces the four artifacts |+| poll **`kicad_progress` / `fusion_progress`** throughout | the bridges DO emit a measured `progress` block: percent, ETA, cold/warm |++The page scores the result **N/3 and only 3/3 is a pass**, on the stated+principle that *a library with a symbol but no 3D model is not a working+library*.++So the bundle is not missing from the product — it is missing from any harness+that calls one verb and screenshots the window. Measured live on crr:++```+show_symbol starting     -  0% -  7s left - warm+show_footprint starting  - 45% - 12s left - warm+```++**Before filing a bridge bug, check whether the UI path does something you+skipped.** Drive the part through the page first (§2) and read the card's own+log — it narrates every step it takes.++What is genuinely worth reporting is a verb that succeeds while its own+precondition is unmet and says nothing: `fusion_show_library` returning+`success: true` with `3D bound: false` is a missing hint, not a broken bridge.++---++## 1b. The surface matrix — run ALL of these, not just Library++The web-control page has one button per content type, for **both** apps. Most+runs so far have exercised only **Library ("proves all 3")** — which means the+individual-artifact and board/project surfaces are largely UNTESTED, and that is+where the next edge cases live. A real user clicks any of these, so test all of+them.++| surface | KiCad button | Fusion button | what "works perfectly" means |+|---|---|---|---|+| **Symbol** | Symbol (`kicad_show_symbol`) | Symbol (`fusion_show_symbol`) | the part's schematic glyph drawn, its own geometry, correct title |+| **Footprint** | Footprint (`kicad_show_footprint`) | Footprint | the pad layout for that package, right pad count/shape |+| **3D chip / package** | 3D chip (`kicad_show_3d`) | 3D package | the part's OWN STEP body, not a Placeholder slab (§3.4) |+| **Library (all 3)** | Library — proves all 3 | Library — proves all 3 | symbol + footprint + 3D, N/3 = 3/3 |+| **Schematic** | Schematic | Schematic | just this part placed on a sheet |+| **2D board** | 2D board (tight edge cuts) | 2D board (part placed) | part placed on a board, edge cuts |+| **3D board** | 3D board (real 3D body) | 3D board | the real 3D body ON the board |+| **Project** | Project (top of the tree) | Project (top of the design) | the whole project/design opens |+| **State** | Show KiCad state (every window) | — | every window captured, incl. error dialogs |++**Each surface owns fewer artifacts than Library, so its false-success modes+differ** — e.g. a bare Symbol capture can be a stale window (§3.1) with no+footprint/3D to cross-check, so the title assertion matters MORE there, not less.+Rotate through the surfaces across runs; a scenario found on the 3D-chip button+may never surface on the Library button.++**Vary the PARTS too.** Edge cases cluster by part shape: multi-unit symbols,+parts whose declared name ≠ filename (§3.2), parts with no 3D model, polarized+vs non-polarized, connectors, ICs with many pins, LEDs, ferrites. A 10-part run+of all capacitors proves less than 10 parts spanning cap/resistor/inductor/LED/+connector/IC. The wiki has dozens — pull a diverse set each run.++---++## 2. Drive it from the web-control page, in pup++The point of the exercise is the wiki's Quick Actions surface. Calling the verbs+straight over the relay tests the bridge but shows the human nothing about the UI+they are shipping.++**⭐ SHOW THE HUMAN THE WEB-CONTROL DEMO RENDERED IN PUP, EVERY RUN — this is a+standing deliverable, not an afterthought.** John, repeatedly: *"every time i ask+you to run tests you're supposed to show me your web control in pup so i can see+generally what the ui will look like in the wiki with colby's quick actions."* The+demo page IS the surface real users will click in the wiki, so a run owes him a+look at it — the actual rendered UI, not just "the test passed." Do it by+mechanism so you cannot forget:++- **At the START of every run**, `pup_screenshot {fullPage:true}` the page and+  `SendUserFile display:"render"` it, captioned as "the web-control UI the wiki+  quick-actions will render." A live mid-run shot (cards showing progress ++  evidence thumbnails) is even better than a cold one — it shows the UI *working*.+- This is SEPARATE from the per-component artifact images (§5). The pup-UI shot is+  "here is the surface"; the artifact images are "here is what the import+  produced." A run shows BOTH.+- `pup_screenshot` writes into the container filesystem (`savedTo` is a WSL path);+  copy it out before `SendUserFile`.+++**ab already serves the demo. Do not copy the HTML anywhere.** It is on+`http://127.0.0.1:24681/` on every machine with ab installed (`web_demo.rs`,+`DEMO_PORT`), and that exact origin is the sole entry in `BUILTIN_WEB_ORIGINS`+in `direct_api.rs` — pre-trusted, so commands are not gated behind a per-origin+grant.++```bash+# open ab's OWN demo server in Chrome for Testing ON THE MACHINE UNDER TEST+adom-bridge --target <machine> pup_open_window \+  '{"url":"http://127.0.0.1:24681/","width":1500,"height":1000}'++# drive the real buttons, screenshot the real UI+adom-bridge --target <machine> pup_eval '{"sessionId":"...","expression":"..."}'+adom-bridge --target <machine> pup_screenshot '{"sessionId":"...","fullPage":true}'+```++Notes that cost time to learn:++- **`file://` does not work.** It is an opaque origin, and ab hard-refuses+  commands from those: *"Adom Bridge refuses commands from an opaque origin+  (Origin: null)"*. The page will fetch the part's files from the wiki fine and+  then fail on the first `write_file`, which reads like a bridge bug and is not+  one. Serving the copied HTML yourself is also a dead end — a hand-rolled+  static server is a *different* origin and lands you back in the Allow/Deny gate.+- Don't reach for `python -m http.server` on a Windows target anyway: `python`+  there is usually the **Microsoft Store stub**, which exits immediately, so+  `launch_process` returns a pid and nothing ever listens.+- The verb family is **`pup_*`**. `browser_*` is gone — the alias only survives+  as a hint telling you to rename.+- `pup_screenshot` writes into the **container** filesystem (`savedTo` is a WSL+  path). Copy it out before trying to read it.+- The page talks to `127.0.0.1:24680`, i.e. **the machine the browser is on**.+  Run the browser on the machine under test or you are testing the wrong PC.+- Omit `sessionId` on the first open and the thread gets its own window; reuse+  that id afterwards.++---++## 2a. Running the batch reliably — the harness lessons++Everything here cost a restart to learn on crr (2026-08-25). None of it is the+bridge's fault; it is what a batch runner must handle.++### The environment fights you two ways — automate both++- **The web-control grant caps at 1 HOUR, and a 10-part Fusion pass runs ~55 min.**+  It WILL lapse mid-run, and the symptom is a part that captures the symbol ++  footprint then fails on the 3D step with *"did not approve this web page to run+  this verb."* Don't hand-click Allow each time — **re-grant from the runner+  before every part**: check `web_control_grants`; if the timed grant for+  `http://127.0.0.1:24681` has < ~5 min left, raise the prompt (click any library+  button), surface ab (`desktop_window_show {hwnd}` → `desktop_raise_window`),+  find the teal *Allow 1 hr* button in a window capture, map image→screen through+  the window rect, and `desktop_click` it. Verify the grant went `mode:"timed"`+  before proceeding.+- **The screensaver (`adom-screensaver.scr`) steals foreground AND blanks every+  capture.** When it owns the desktop, `desktop_get_foreground` returns hwnd `0`,+  your Allow click never reaches ab's WebView, and screenshots come back white.+  **Kill it before every grant attempt and before every capture** (`process_list+  {name:"scr"}` → `process_kill` each `.scr`). This is §3.5 as an active step, not+  just a check.++### `desktop_window_show`/`desktop_click` succeed without doing anything++Both return `{success:true}` even when the window never surfaced or the click+never landed. To actually grant: `desktop_window_show {hwnd}` → `desktop_raise_window+{hwnd}` → **confirm `desktop_get_foreground` == that hwnd** → then click. If+foreground is `0` or something else, the screensaver or another window has it —+clear that first. `success:true` on a click is not proof the pixel was hit.++### Four runner bugs that all looked like bridge failures++1. **Completion detection: poll `btn.disabled`, NEVER the word "running".** The+   demo disables the card's button for the whole run and re-enables it on every+   exit path — that flag is the one true "done" signal. The progress block+   REPLACES the running text mid-run, so a text check declares FAIL at 10s while+   the bar is at 85%.+2. **Pull each evidence `<img>` ONE AT A TIME.** Three ~175 KB data-URLs in a+   single `pup_eval` result overflow it and come back empty — so every part+   silently saved 0 artifacts. Get the count + labels first (tiny), then fetch+   each `img[i].src` in its own eval.+3. **Extract by the BUTTON index, not the loop counter.** A capture bug hid here+   for two runs: the poll used the button index (25) but the extractor was passed+   the 1..10 loop counter, so it read a different, empty card. Same index for+   poll and extract.+4. **Reload the page before the run to clear WEDGED card state.** Repeated+   interrupted clicks leave a card's per-run JS promise wedged; the next click+   disables the button then throws before the first log line, and the part hangs+   to the loop cap producing nothing. A fresh `pup_navigate` clears it — do it+   once at the start of every run.++### Fusion cold-start and document accumulation++- **The *"Loading additional modules"* window is a VISIBLE:FALSE ghost — do not+  treat its presence as "still loading" (corrected 2026-08-26).** Fusion leaves a+  nearly-fullscreen `Loading additional modules` window in `desktop_enum_windows`+  with **`visible: false`**, and it NEVER disappears — so a check for the title+  alone waits forever for a window that is not actually blocking anything. When+  you gate on it, **filter `visible == true`**: a *visible* loading window means+  genuinely still loading; an invisible one is a leftover Fusion keeps around on a+  fully-loaded instance (measured: 1.7 GB RSS, 4600 handles, with the ghost still+  enumerated). If part 1 still hangs on "waiting for idle" with no *visible*+  loading window, the cause is the cold add-in or doc state, not module loading —+  a throwaway warm-up part or a `fusion_close_all_documents` is the lever, not+  more waiting.+- **Close documents BETWEEN Fusion parts** (see §3.4a). A 10-part run left **64+  documents** open on crr, which slowed the 3D step until it blew ab's 60s budget+  on every part after the first. Call `fusion_close_all_documents` between parts.+  If the pile-up already happened (`fusion_get_app_state.documents` in the dozens),+  a full Fusion restart is the only clean reset — `close_all` won't force-close+  the stray `Untitled` docs.++### Timing to expect (post-fixes, crr)++KiCad via the UI: ~54 s/part, steady. Fusion via the UI: ~40 s warm per part once+Fusion is settled and documents are closed between runs; the FIRST part after a+cold start pays a multi-minute module-load tax. Budget the whole Fusion pass at+~50–60 min and let the self-granting runner carry it across the 1-hour grant.++---++## 3. The five false successes++Each of these produced a green flag and a plausible-looking screenshot.++### 3.1 Stale window (KiCad)+A failed open leaves the **previous** part on screen. The capture is full of ink,+the symbol is real — it is just the wrong component.++> **Check:** the window title must contain the part you asked for.+> ```python+> ws = call("desktop_enum_windows", {"includeOffscreen": True})+> assert any(want.lower() in (w["title"] or "").lower() for w in ws["windows"])+> ```++### 3.2 Name mismatch (KiCad)+The symbol name **inside** the `.kicad_sym` is often not the filename.+Measured: `CL21A226MPQNNNE` declares itself `CL21A226MPQNNN` — the trailing `E`+is dropped. Asking for the file stem finds nothing, and 3.1 then shows you the+last part instead.++> **Check:** parse the declared name out of the file and ask for *that*.+> ```python+> for m in re.finditer(r'\(symbol\s+"([^"]+)"', text):+>     if not re.search(r"_\d+_\d+$", m.group(1)):   # skip _1_1 sub-units+>         return m.group(1)+> ```++### 3.3 Blank workspace (Fusion)+Fusion can land on an empty `Untitled` **Design** tab while the part's tab sits+unfocused in the tab bar. The verb reports success. The capture is a huge empty+dark canvas.++> **Check:** the *active* tab's title must be the part, and the Electronics+> panels (Symbol / Component Properties / Packages) must be present. An empty+> SOLID/SURFACE/MESH ribbon means you are in Design, not the library.++### 3.4 Placeholder 3D (Fusion) — usually YOUR bug, not the bridge's+The 3D preview pane renders a generic grey block for parts with no mapped+package. It looks like a chip. It is **byte-identical** across a capacitor, a+resistor, a ferrite bead and an LED.++**First suspect §1a: did you call `fusion_bind_library_3d` before opening?** If+not, the Placeholder is correct behaviour and there is nothing to report.++### 3.4a 3D-package step times out at ab's 60s budget (Fusion)+A part captures symbol + footprint, then the 3D step fails with *"did not respond+within ab's 60s budget."* First part of a run works, later parts fail. This is+**document accumulation**, not a bridge bug — the Fusion thread's own 1.9.209 note+predicted it: each part opens a library doc + a bound-3D doc, they pile up (64+open on crr by the end of one run), and Fusion slows until the cloud-3D step+exceeds 60s. **Fix: `fusion_close_all_documents` between parts** (its own+`openDocuments` hint tells you to). If the pile-up is already there, restart+Fusion for a clean slate. Verify it's this and not a grant lapse (§2a) by reading+the card tail: a grant lapse says *"did not approve this web page"*, a real 60s+timeout says *"did not respond within ab's 60s budget."*++> **Check:** hash the 3D pane across the batch. Identical hashes = placeholder,+> not the part's model. Also read the Packages table: `Package: Placeholder`+> says it outright.+> ```python+> box = (782, 500, 930, 655)         # 3D pane, 1200px-wide capture+> h = hashlib.md5(Image.open(f).convert("RGB").crop(box).tobytes()).hexdigest()+> ```++### 3.5 Screensaver+`adom-screensaver.scr` covers the desktop and every capture comes back white —+indistinguishable from a symbol that failed to render. It cost an hour once.++> **Check:** kill it before each capture.+> ```python+> for p in call("process_list", {"name": "adom-screensaver.scr"})["processes"]:+>     call("process_kill", {"pid": p["pid"], "reason": "..."})+> ```++---++## 4. Ink percentage is not a content check++Measure it if you like, but it certifies nothing:++- KiCad passes clustered at **40%** whether the symbol was right or **wrong**+  (§3.1) — the surrounding editor chrome dominates the frame.+- The Fusion **blank workspace** scored **99.5%**, the *highest* in its batch,+  because a uniform dark canvas is "inked" everywhere.++Ink detects one thing only: a totally white frame (§3.5). Treat it as a smoke+alarm, never as a verdict.++---++## 5. Reporting — SHOW the human the pictures, do not describe them++**The cardinal reporting rule: the human verifies the import with their OWN eyes.+Your job is to put the image in front of them, per component, inline. Your words+go WITH the picture, never instead of it.** A text description ("I verified the+LED glyph") asks them to trust your eyes — which is exactly what the evidence+contract exists to remove. John's repeated correction: *"you barely ever show me+images inline in the chat proving the output of the import."* Fix that by+mechanism, not by trying harder to describe.++### The mechanism, exactly++- **`Read`ing an image shows it only to YOU.** It is how you eye-verify content —+  necessary, but it proves nothing to the human. Do not confuse "I Read it" with+  "I showed it."+- **`SendUserFile` with `display: "render"` is how you SHOW the human.** It+  renders the actual image inline. Use it for **every artifact you want them to+  see** — which is all of them.+- So the loop per component is: **Read each artifact (verify) → SendUserFile+  `display:"render"` the same artifacts (show) → then your one-line read as the+  caption or the following text.** The picture leads; the words follow.++### What that looks like in practice++- **Per component, send its artifacts as their own images**, not a page+  screenshot with the artifacts as tiny tiles buried in it (John, 2026-08-25:+  *"why are you giving me back screenshots of the ENTIRE page... i just want to+  see the evidence of each library import"*). Pull each artifact's own `<img>`+  from the card (§2a "pull each image one at a time"); those are full-res+  captures, not thumbnails.+- **Caption every send with the read** — what you expected and what you actually+  saw ("3D pane: real bound body, `Package: 0402B103J500CT · Mapped`, NOT a+  Placeholder"). The caption is the report; the image is the proof. Both, every+  time.+- **A summary table is not evidence.** It can accompany the images, never replace+  them.+- Don't silently batch ten components into one dump at the very end and skip the+  in-between. Send evidence as it lands so the human watches the campaign, and can+  redirect early (SendUserFile's own guidance). If you must batch to avoid noise,+  batch a *component's* artifacts together — never drop the images entirely.++### The rest of the report++- **Read every image.** Not a sample. Not "the flags agree". Every one.+- Count content passes, not flag passes, and show both when they disagree —+  the disagreement is the most valuable output of the run.+- When something is wrong, the failing image is the MOST important one to send —+  show the Placeholder slab, the stale window, the blank Design tab. Do not+  describe a failure you are hiding.+- File what you found on the owning bridge's wiki repo (`adom/kicad-bridge`,+  `adom/fusion-bridge`, `adom/pup-bridge`) with the verbatim response JSON and+  the bridge version from `bridge_list`.++## 6. Timing, so the progress bar can be honest++Measured on ConfRoomROG, 10 parts, warm apps:++| verb | typical | outlier |+|---|---|---|+| `kicad_show_library` | ~72 s | ~150 s, roughly half of opens |+| `fusion_show_library` | ~27 s | 40 s on the first (cold) part |++The KiCad split is bimodal and does **not** track library size. Do not promise+an ETA tighter than the outlier; report `confidence: estimated` until a bridge+ships a real `progress` block.++---++## 7. Edge-case catalog (living) — the point of the campaign++Every scenario a run turns up goes here, with where it was fixed. **Add a row the+moment you find something new; update the status when it is fixed; re-run to+confirm and note the confirming version.** This table is what makes repeated runs+compound into coverage. Keep it current — a finding that lives only in a chat+message is lost.++Status legend: **OPEN** (found, not yet fixed) · **FIXED** (fix shipped, cite+where) · **CONFIRMED** (re-run passed on the fixed version).++| # | scenario | surface | class | status / where fixed |+|---|---|---|---|---|+| 1 | `kicad_show_library` returns `success:true` with the **PREVIOUS part still on screen** (stale window) — a green flag over the wrong component | KiCad | kicad-bridge | **OPEN** — filed kicad-bridge#62 (Finding 1); ask: `success:false` + `symbol_not_found` + echo `resolvedSymbol` |+| 2 | symbol name INSIDE the `.kicad_sym` ≠ the filename (`CL21A226MPQNNNE` declares `CL21A226MPQNNN`, trailing E dropped) — asking for the file stem finds nothing | KiCad | kicad-bridge | **OPEN** — kicad-bridge#62 (Finding 2); harness parses the declared name; ask: accept MPN alias or add `kicad_list_symbols` |+| 3 | `fusion_show_library` `success:true` but 3D pane is a **byte-identical Placeholder slab** — because `fusion_bind_library_3d` was not run first (§1a) | Fusion | fusion-bridge | **FIXED** 1.9.209 — returns `threeDBound` + hint; was my own wrong report, retracted |+| 4 | `fusion_show_library` `success:true` with an **empty `Untitled` Design tab** active (wrong active document); scored HIGHEST ink (99.5%) | Fusion | fusion-bridge | **FIXED** 1.9.209 — asserts active doc == library, else `library_not_active` |+| 5 | **document accumulation** across a run (64 docs open) slows Fusion until the **3D step exceeds ab's 60s budget** on later parts | Fusion | fusion-bridge + harness | **FIXED** 1.9.209 (`openDocuments` hint) + harness `fusion_close_all_documents` between parts (§3.4a) |+| 6 | the "**Loading additional modules**" window is a `visible:false` GHOST that never disappears — gating on its title alone waits forever; the real cold-start hang is add-in/doc state, not module load | Fusion | harness | **FIXED** — skill §2a: filter `visible==true`; warm-up part / close-docs for the real hang |+| 7 | `process_list` with an **unrecognized filter key** (`{name:...}` vs its `nameFilter`) returned **EVERY process** with `success:true` → an AI kill-loop took the whole machine (and Hydrogen) down | ab core | ab core | **FIXED + CONFIRMED** ab 2.0.80 — `name`/`pid` aliases, unknown key refused, `unfiltered`+`_warning` |+| 8 | web-control **grant caps at 1 hour**; a ~55-min Fusion run lapses mid-part → symbol+footprint captured, 3D fails "did not approve" | harness | harness | **FIXED** — skill §2a: runner re-grants (kill screensaver, surface ab, click Allow 1 hr) before each part |+| 9 | **screensaver** (`adom-screensaver.scr`) steals foreground (Allow click misses) AND blanks every capture white | environment | harness | **FIXED** — skill §2a/§3.5: kill it before every grant + capture |+| 10 | web-control **progress bar painted RED "stopped" on a successful 3/3** — read the outcome off the card class before `setRes` wrote it | demo page | demo page | **FIXED + CONFIRMED** — outcome passed explicitly at all 6 call sites; 8 unit tests |+| 11 | evidence extraction saved **0 artifacts** though the parts passed — three runner bugs: text-based completion detection, 3×175KB data-URLs overflowing one `pup_eval`, extracting by loop-counter not button index | harness | harness | **FIXED** — skill §2a "four runner bugs" |+| 12 | repeated interrupted clicks **wedge a card's JS promise** — next click disables the button then throws before the first log line; the part hangs to the loop cap | demo page / harness | harness | **FIXED** — skill §2a: `pup_navigate` reload before each run |+| 13 | after a "clean" Fusion **restart** the library open did not activate (`show_symbol` failed "No symbol named X") — a blank Untitled was active with stale tabs from a DIFFERENT part | Fusion | harness | **RESOLVED (harness)** — ROOT CAUSE: stale tabs from a prior session; a kill-restart TRIGGERS Fusion session-restore and brings them BACK. Fix: **gracefully `fusion_close_all_documents` BEFORE the run** (leaves nothing to restore), never kill-restart. Isolated with a single-part test: with tabs cleared the library activated (`activeDocument: 0402B103J500CT`) and 3/3 passed. NOT a bridge bug — verified before filing |+| 14 | Fusion **symbol-surface capture is flaky**: sometimes a dedicated symbol-editor view, sometimes a fallback whole-window grab. The symbol itself is present + correct either way (import is fine); only the evidence-capture path varies, so a strict N/3 scores 2/3 on the fallback | Fusion | fusion-bridge? / page | **OPEN, low severity** — NOT an import failure (the symbol is correct in both); it is capture inconsistency. Track how often across a run before filing; the import is good regardless |+| 15 | the library/bind flow **leaks `Untitled` 3D docs that accumulate unbounded** (~5 per import → 16 after 3 imports → ~50 over a 10-part run), and `fusion_close_all_documents` CANNOT close them (they resist as unsaved) — the root of the memory pressure behind #5's 60s timeout | Fusion | fusion-bridge | **OPEN** — filed fusion-bridge#59 (John spotted it); ask: close/reuse the scratch Untitled, or expose a force-close for a caller |+| 16 | on a LONG unattended REMOTE run the 1-hour web-control grant lapses mid-run, and the harness re-grant is FRAGILE: the Allow-button click misses when the ab window moves or the screensaver steals foreground, so parts start failing GRANT FAILED | harness / ab | harness / ab-core | **OPEN** — harness re-grants but the pixel-click is unreliable on a remote box. Real ab-core question: an unattended-run grant mode, a >1h option, or a CLI/owner-grantable path so a long remote campaign is not gated on a fragile UI click |+| 17 | **symbol text-overlap**, MEASURED + SYSTEMATIC: some components' `.lbr` place `>NAME`/`>VALUE` at y≈0 (on the symbol body, and CQ03SAF1004T5E has BOTH at y=0, on each other) instead of ±10 like clean parts. Broken: CQ03SAF1004T5E, CL21A226MPQNNNE. Clean: 0402B103J500CT, 0603X475K100CT (y=±10). Fusion renders the bad `.lbr` faithfully | component-data / .lbr-generator | NOT the bridge | **OPEN, routed to the .lbr converter/linter** — a `.lbr`-generation inconsistency, SCANNABLE library-wide (fetch each `.lbr`, flag `>NAME`/`>VALUE` y near 0 / on the pin span). The automated symbol-label-overlap check, proven in practice. Import 'succeeds' (3/3, 3D mapped) but the symbol is visually wrong |+| 17a | **library-wide scan of #17** (50 components): **9 resistors have `>NAME`+`>VALUE` both at exactly y=0** (stacked, on body) — CR0603-FX-5601ELF, RMCF0603FT1R50, CQ03SAF1004T5E, 0603SAF1500/1/2/3T5E, 0603WAF100JT5E, CR0402-FX-1000GLF — a resistor-symbol-generation bug. 5 large ICs flagged but likely OK (labels at pin-span edge). ⚠ the naive "label-y within pin-span" check MISSED CL21A226MPQNNNE (±0.63, pins at 0) — false negative | component-data / .lbr-generator | NOT the bridge | **OPEN** — the real geometry check needs actual symbol-body extent + text height (true bbox overlap), not pin-span. 9-resistor list is definitive + actionable |++**Still-untested surfaces (expect new rows here):** every non-Library button in+§1b — Symbol / Footprint / 3D-chip / Schematic / 2D-board / 3D-board / Project,+for both apps. And parts beyond the passives-heavy sets run so far (connectors,+multi-pin ICs, multi-unit symbols, no-3D parts).++---++## 8. The feedback loop — route every finding to its owner++A found scenario is only half the work; the value is the fix, and the fix must+land in the RIGHT place or it does not stick. Classify every catalog row:++- **ab core** (`C:/Github/adom-bridge`) — the verb surface, the relay, the demo+  page, screenshots, process/window verbs, the grant model. You OWN this: fix it,+  bump the version, release (the release ladder in CLAUDE.md), and re-run to move+  the row to CONFIRMED. Example: #7, #10.+- **kicad-bridge / fusion-bridge** — anything about how the library/symbol/+  footprint/3D verb behaves inside the app. You do NOT own these (cloud-owned+  wiki repos). File a precise issue on `adom/kicad-bridge` or `adom/fusion-bridge`+  with the verbatim response JSON + the bridge version from `bridge_list`, then+  watch for their fix and re-run against it. Example: #1, #2 (open), #3, #4, #5+  (fixed by the fusion thread in 1.9.209 — re-run to confirm).+- **harness** (`C:/tmp/libui.py`, `regrant.py`) — the runner, the grant flow, the+  capture. Fix the script; the lesson also goes into this skill (§2a) so the next+  run inherits it. Example: #6, #8, #9, #11, #12.+- **this skill** — every lesson, always. A fix that isn't written down is+  re-learned. The catalog (§7) + §2a are the durable memory of the campaign.++**The discipline:** after each run, for anything new — (1) add the catalog row,+(2) name its class, (3) fix it there or file it there, (4) re-run to confirm.+When you fix an ab-core or harness item, the confirming re-run is part of the+same session. When you file a bridge item, the confirming re-run happens after+the bridge thread ships — the wiki-issue watcher (a background poll of the issues+you filed) tells you when to look.++**Watch your own issues.** After filing on a bridge, keep a light background+watch on those issues so a shipped fix (like fusion-bridge's 1.9.209) is picked+up and re-tested promptly, rather than sitting unconfirmed.++---++## 9. What a run leaves behind — the local import ledger (pre-wiki)++Before asking the wiki for an attestation/counter feature, **track imports+locally and get real experience with the data.** Act like a normal Adom user+keeping a record of their own imports; see what's actually useful and trustworthy+first, then spec a feature backed by evidence rather than a guess.++`C:/tmp/ledger.py` writes `C:/tmp/import-ledger.json`, keyed+`component → app → {verified_imports, runs[]}`. The harness records each part+automatically. Design rules, all about not fooling ourselves:++- **Objective fields are recorded by machine, subjective ones stay `null` until+  reviewed.** Recorded automatically: timestamp, ab + bridge versions, duration,+  `flag_pass` (the verb's `success`), and each artifact's **filename + sha256**+  (an attestation must carry a hashable image — a flag is a claim, an image is+  proof). Left `null` until a human/AI reads the pictures: `content_verified`,+  `notes`, and the `geometry` block (`3d_bound`, `text_overlap`,+  `3d_alignment_offset`).+- **`verified_imports` NEVER counts a `content_verified:false` run.** A flag pass+  with the image not yet reviewed counts provisionally; a reviewed-bad run is+  excluded. The count is honest by construction — it can't drift green.+- **The geometry slots are where §the-quality-plan lands.** They're `null` now;+  as we build the checks (symbol text-overlap from the kicad-cli SVG export;+  3D-body-center vs footprint-center offset) they get filled with measured+  numbers, and later become bridge verbs so every import — not just our test+  runs — gets the objective signal.+- **The aggregate is a quality breakdown, not a bare tally.** `ledger.py`'s+  summary reports imports / flag-ok / reviewed per component+app, so+  "imported N times" always carries how many were actually verified. When this+  graduates to the wiki, the count publishes with that breakdown, never alone.++The two signals stay split (see the design discussion): the **quality+attestation** (git file, owner-written — us) and the **field-import count**+(a wiki-DB counter via an authenticated `import-events` endpoint, because a+non-owner user can't write the page's files). We build the local ledger now; we+spec the wiki endpoint only once the local data has taught us what to ask for.++---++## 8a. Filing a bridge issue, and watching for the fix — the mechanics++§8 says "file it on the bridge and re-run when they ship." Here is exactly how,+because the details bite.++### Why it MUST be a wiki issue (not a message)++The kicad/fusion bridge threads run under a DIFFERENT Adom account+(`[email protected]`) than this campaign typically does (`[email protected]`), so+you **cannot `@mention` or `SendMessage` them** — they will not appear in your+reachable-agents list. **The bridge's wiki discussion is the only channel that+reaches its author**, and per CLAUDE.md it is their actual work queue. So a+finding routed to a bridge is a wiki issue, full stop.++### Filing (verified commands)++```bash+# 1. check for a duplicate first+adom-wiki issue list adom/fusion-bridge          # or adom/kicad-bridge, adom/pup-bridge++# 2. write the body to a FILE - never inline --body:+#    the body has backticks and JSON braces, which the shell / the CLI's inline+#    parser mangle ("unexpected argument", "invalid escape"). --body-file is safe.+adom-wiki issue create adom/fusion-bridge \+  --title "<one-line symptom>" --category bug-report \+  --body-file /c/tmp/issue_fusion.md+```++The body must carry, every time: the **verbatim response JSON**, the **bridge+version from `bridge_list`**, ab's version, the OS, and the exact repro (which+button/verb, which part). A finding without the verbatim response is not+actionable. Attach or reference the evidence images.++**Correct yourself in the SAME thread if you were wrong.** Twice this session a+filed finding turned out to be my own error (I skipped `fusion_bind_library_3d`;+I snap-diagnosed a name mismatch the file disproved). The fix is a follow-up+COMMENT that withdraws the wrong part and narrows to what survives — never a+silent delete:++```bash+adom-wiki issue comment adom/fusion-bridge#58 --body-file /c/tmp/correction.md+```++A retraction with the evidence is worth more to the maintainer than a report+polished until it was safe to send. It also keeps YOUR credibility as a reporter.++### The concatenated-JSON caveat++`adom-wiki issue view` / `issue list` output is often **several JSON documents+concatenated**, so a single `json.load` throws `Extra data`. Parse with a decoder+loop:++```python+from json import JSONDecoder+s = subprocess.run([...], capture_output=True, text=True).stdout+d, i = JSONDecoder().raw_decode(s)          # first doc; or loop raw_decode(s, i)+disc = d.get("discussion") or d+replies = d.get("replies") or disc.get("replies") or []+```++Also: on Windows, force UTF-8 stdout in the parser or a `\u2192`-class char kills+it with `UnicodeEncodeError` under cp1252.++### Watching for the fix (the watcher)++After filing, keep a light background poll over the issues you opened so a shipped+fix is picked up promptly instead of sitting unconfirmed. The pattern+(`C:/tmp/wiki_watch.py`): every ~2.5 min, `issue view` each filed ref, track the+reply count on disk, emit a line only when a NEW reply lands or the status flips.+Run it as a persistent background monitor; a new-reply event is your cue to READ+the reply and **re-run the affected surface against the shipped version** to move+the catalog row (§7) from OPEN → CONFIRMED.++This is not hypothetical: this session the fusion thread replied on #58 that all+three findings were fixed in **1.9.209** — the watcher is what turns "they+replied" into "we re-tested and confirmed" without you having to remember to+check. The whole loop only closes when the confirming re-run is done and the+catalog says CONFIRMED, not when the bridge says "fixed."

@@ -0,0 +1,252 @@+---+name: adom-bridge-window-capture+description: The complete reference for Adom Bridge screenshots — every capture verb, the exact JSON response shape (coordMap, shotId, ownedPopupCount, the screenshots[] child-dialog array, windowRect, the multi-monitor display block), and how the CLI automatically stores each shot on disk (the window/ and screen/ buckets, the ISO-stamped filenames, the single-vs-full/safe pair, the .popup-NN grouping, and the <stem>.json sidecar). Read this to drive a GUI app that pops modal dialogs, to capture a backgrounded/occluded window, to understand a multi-monitor grab, or to build a tool (like shotlog) that renders every screenshot shape ab can return. Covers desktop_screenshot_window, desktop_screenshot_screen, kicad_screenshot_all, the coordMap click-what-you-see contract, and the exact on-disk sidecar schema.+---++# Adom Bridge screenshots — full capability, response shape, and on-disk contract++This is the deep reference for everything ab can capture and everything it writes to disk. Two audiences:++- **An AI driving a GUI app** — jump to "The verb map" and "Owned popups". The one thing to internalize: `desktop_screenshot_window {hwnd}` sees a window AND the modal dialogs it owns, in the background, without stealing focus.+- **A tool that renders ab screenshots (e.g. shotlog)** — jump to "On-disk storage" and "The sidecar schema". Every shot lands in a predictable bucket with a self-describing `<stem>.json` next to it; you never have to parse the response envelope, just watch the folder.++---++## 1. The verb map — what each capture verb returns++| Verb | Captures | Foreground? | Shape |+|---|---|---|---|+| **`desktop_screenshot_window {hwnd}`** | ONE window + every child dialog / error box it owns | No (PrintWindow, background) | one parent image + `screenshots[]` array of owned popups |+| **`desktop_screenshot_screen {}`** | the ENTIRE virtual desktop (ALL monitors, stitched into one image) | n/a (whatever is on screen) | one image + a `display` block listing every monitor |+| **`kicad_screenshot_all {}`** | every open KiCad window (main + all dialogs) as separate images | No | an ARRAY of sibling-window images |+| **`browser_screenshot` / `nbrowser_screenshot`** | a browser PAGE / viewport (CDP, not a window grab) | No | one image (page pixels, not window chrome) |+| **`desktop_record_window_start` / `..._screen_start`** | VIDEO (same PrintWindow/WGC family) | No | an `.mp4`, not a PNG (see the recording skill) |++**Rule of thumb:** for one app window, ALWAYS prefer `desktop_screenshot_window {hwnd}` (resolve the hwnd with `desktop_find_window {titleContains}`). It captures even when the window is backgrounded, occluded, or minimized, it never steals focus, and it brings back the app's modal dialogs. Use `desktop_screenshot_screen` only for the whole desktop or for popups not owned by any single window.++---++## 2. The universal response shape (every screenshot verb)++Every ab screenshot response carries the same core envelope. Field-by-field:++```jsonc+{+  "success": true,+  // ── the image, on the DESKTOP (host) side ──+  "fullPath":  "C:\\...\\adom-bridge-shots\\window-<hwnd>-<ts>.full.png", // or a single .png+  "safePath":  "C:\\...\\adom-bridge-shots\\window-<hwnd>-<ts>.safe.png",+  "fullWidth": 3840, "fullHeight": 2160,   // native capture size+  "safeWidth": 1568, "safeHeight": 882,    // downscaled to <=1568px for a model's vision window+  "resizeMax": 1568,++  // ── the image, PULLED to the CALLER (container) side by the CLI (v1.8.61+) ──+  "localFullPath": "/home/adom/project/screenshots/adom-bridge/window/2026-07-15T01-14-16.937-986710.full.png",+  "localSafePath": "/home/adom/project/screenshots/adom-bridge/window/2026-07-15T01-14-16.937-986710.safe.png",+  "localFullExists": true, "localSafeExists": true,+  "fullBytes": 402931, "safeBytes": 88104,   // bytes on the CALLER side+  "source": "printwindow",                    // capture method+  "narrative": "Captured window + 0 owned popups. Pulled full+safe to .../window/.",++  // ── click-what-you-see: bind the delivered image to real screen pixels ──+  "coordMap": {+    "shotId": "shot_a1b2c3",+    "image":  { "w": 1568, "h": 882 },                 // the SAFE image dims+    "screenRect": { "x": 100, "y": 80, "w": 3840, "h": 2160 }, // physical px on the desktop+    "dpiScale": 1.5,+    "imageToScreen": { "sx": 2.449, "sy": 2.449, "ox": 100, "oy": 80 } // px_screen = px_image*s + o+  },++  // ── where the window sits on the (possibly multi-monitor) desktop ──+  "windowRect": { "x": 100, "y": 80, "w": 3840, "h": 2160, "monitor": 1 },+  "display": { /* see §4 multi-monitor */ },++  // ── owned popups (see §3) ──+  "ownedPopupCount": 0,+  "screenshots": [ /* present when ownedPopupCount > 0 */ ],++  "drive": "background",       // this capture never foregrounded the window+  "_related": ["desktop_find_window", "desktop_click", "desktop_ui_click"]+}+```++**`coordMap` + `shotId` is the zero-math contract.** To click something you SEE in the delivered (safe) image, do not do DPI/scale arithmetic. Pass the pixel you see:++```bash+desktop_click '{"space":"image","shotId":"shot_a1b2c3","x":742,"y":410}'+```++ab converts image px → physical screen px via that capture's `coordMap` and clicks. DPI-correct and multi-monitor-correct automatically. The same `{space:"image", shotId, x, y}` works for `desktop_double_click`, `desktop_right_click`, `desktop_hover`, and the read-only `desktop_ui_from_point`.++---++## 3. Owned popups — one window, N child dialogs (the "6 child windows" case)++A native app's modal dialogs ("Save changes?", "DRC found 3 errors", "Export failed", Chromium's "Remove extension?") are **separate top-level windows** that (a) do NOT appear in `desktop_list_windows` and (b) are invisible to a plain PrintWindow of the parent. `desktop_screenshot_window` finds every popup the parent owns and returns each as its own image.++When `ownedPopupCount > 0`, the response gains a `screenshots[]` array — one entry per owned popup:++```jsonc+{+  "ownedPopupCount": 6,+  "screenshots": [+    {+      "hwnd": 265518,+      "title": "Error",+      "kind": "owned_popup",+      "rect": { "x": 900, "y": 500, "w": 420, "h": 180, "monitor": 1 }, // its screen position + monitor+      "fullPath": "...popup .full.png", "safePath": "...popup .safe.png",+      "fullWidth": 420, "fullHeight": 180, "safeWidth": 420, "safeHeight": 180,+      "coordMap": { "shotId": "shot_pop1", ... },   // its OWN coordMap+      "shotId": "shot_pop1",+      // CLI adds after pull:+      "localPath": ".../window/<parentStem>.popup-01.png", "savedTo": "...", "localSafePath": "..."+    },+    { "hwnd": 265702, "title": "Confirm", "kind": "owned_popup", "shotId": "shot_pop2", ... },+    // ... up to popup-06+  ],+  "_popups_note": "READ each popup image — one is usually the blocking dialog. Act on it via {space:\"image\", shotId, x, y} or desktop_ui_click {scope:\"popups\"}."+}+```++So a window that owns 6 dialogs returns **1 parent image + 6 popup images = 7 images**, each independently clickable via its own `shotId`. To act on a dialog's button without stealing focus, prefer the accessible-name path:++```bash+desktop_ui_click '{"scope":"popups","name":"OK"}'   # background Invoke by name, targets an owned dialog+```++**`kicad_screenshot_all` is the sibling-window variant:** it returns an ARRAY of every open KiCad window (main editor + each dialog) as top-level siblings (not an owner tree). Same per-image shape; use it when the app's windows are peers rather than parent/owned.++---++## 4. Multi-monitor — how a full-desktop grab comes back++**`desktop_screenshot_screen` today returns ONE image that spans the entire virtual desktop** — both monitors stitched side by side (it captures `SM_XVIRTUALSCREEN..SM_CXVIRTUALSCREEN`, the union bounding box of all monitors). It does NOT return one image per monitor. Alongside the image it returns a `display` block describing the layout so a caller (or a renderer) can slice the stitched image back into per-monitor regions:++```jsonc+"display": {+  "virtualScreen": { "x": 0, "y": 0, "w": 3283, "h": 1440 }, // the union = the stitched image's screen rect+  "primary": { "w": 1440, "h": 900, "dpi": 96, "scale": 1.0 },+  "monitors": [+    { "index": 0, "device": "\\\\.\\DISPLAY1", "primary": true,  "bounds": {"x":0,"y":0,"w":1440,"h":900},+      "logicalBounds": {"x":0,"y":0,"w":1440,"h":900}, "scale": 1.0, "dpi": 96 },+    { "index": 1, "device": "\\\\.\\DISPLAY2", "primary": false, "bounds": {"x":1440,"y":0,"w":2304,"h":1440},+      "logicalBounds": {"x":1440,"y":0,"w":1843,"h":1152}, "scale": 1.25, "dpi": 120 }+  ],+  "monitorOfWindow": 1+}+```++**The authoritative monitor map is `desktop_list_monitors`** (v1.9.119+): every monitor with `bounds` (PHYSICAL px, the same space `desktop_set_window_bounds` uses), `logicalBounds` (DIPs, what a browser's `screen` object reports), `workArea`, `scale`, `dpi`, `primary`, `index`, `device`. Physical vs logical differ on a scaled/high-DPI display; the `units` hint in the response spells out which field is which.++**Two ways to get per-monitor images (v1.9.121):**+- **`desktop_screenshot_screen {monitor: N}`** — capture ONLY display N (0-based, from `display.monitors`). Returns the normal single-image shape (fullPath/safePath/coordMap/dimensions) PLUS a `monitor:{index,bounds,logicalBounds,scale,dpi,primary}` block. The `coordMap.screenRect` is that monitor's physical bounds, so an image click lands on that display.+- **`desktop_screenshot_screen {perMonitor: true}`** — returns the stitched all-monitors image at the top level (the "full-full" view) PLUS a `screenshots[]` array with ONE entry per monitor. Each entry: `{index, primary, bounds (physical px), logicalBounds (DIPs), scale, kind:"monitor", fullPath, safePath, coordMap, shotId}` — the SAME array contract as owned popups, so the CLI auto-pulls each tile and names it `<stem>.monitor-NN` under `screen/`. Plus `monitorCount` + a `_monitors_note`.++**How a renderer (shotlog) should show a multi-monitor grab:**+- If the response has a `screenshots[]` of `kind:"monitor"` (perMonitor call), render each monitor tile as its own image (caption from `index`/`primary`/`bounds`), grouped under the stitched top-level image. The tiles share the parent stem with a `.monitor-NN` tag on disk.+- If it is the default single stitched image, render it as-is and (optionally) use `display.monitors[]` to draw monitor boundaries or offer a "just monitor N" crop: monitor N's slice is `bounds[N]` offset by `-virtualScreen.{x,y}` (physical px map 1:1 to stitched-image px before the safe downscale; after downscale, multiply by `safeWidth/fullWidth`). Or just call `{monitor:N}` and let ab capture that display natively.+- On a multi-monitor desktop the default response carries a `_monitorsHint` naming the `{monitor:N}` / `{perMonitor:true}` options.++---++## 5. On-disk storage — where the CLI auto-pulls every shot (the shotlog contract)++The CLI auto-pulls every screenshot (the v1.8.61 universal delivery contract) to the CALLER's machine and self-janitors it. This is the part a visualizer watches.++**Directory (resolved once, per machine):**+```+$ADOM_SHOTS_DIR                                  # explicit override, else:+~/project/screenshots/adom-bridge/              # when ~/project exists (the container convention)+~/.adom/screenshots/                             # fallback (off-container / Windows, no ~/project)+```+Never `/tmp`. ab deliberately does NOT touch `~/project/screenshots/*.png` (timestamp-named) or `~/project/screenshots/shotlog/` — those belong to other tools.++**Buckets (subfolders by kind):**+```+<shots_dir>/window/     # a specific window / app / owned popup  (desktop_screenshot_window, kicad_*, pup_*)+<shots_dir>/screen/     # a full-desktop grab                    (desktop_screenshot_screen)+```++**Filenames — human-readable, sortable, self-grouping:**+```+window/2026-07-15T01-14-16.937-986710.png            # <ISO-stamp>-<hwnd>.png   (a window; the folder says "window", so no prefix)+window/2026-07-15T01-14-16.937-986710.popup-01.png   # its 1st owned popup  (shares the parent stem)+window/2026-07-15T01-14-16.937-986710.popup-02.png   # its 2nd owned popup+screen/2026-07-15T01-05-08.625.png                   # a full-desktop grab (no hwnd)+```+The ISO stamp is `YYYY-MM-DDThh-mm-ss.mmm` with no colons, so it is filename-safe AND lexicographic order == chronological order. A `.popup-NN` tag shares the parent's stem, so a plain `ls` shows a whole capture (parent + its dialogs) grouped, and the parent/child role is visible without opening any JSON.++**Single file vs full/safe pair (dedup, v1.9.114):**+- If the shot was already within the safe size cap (<=1568px, the common case) it is written **ONCE** as `<stem>.png`, and `localFullPath == localSafePath` point at that one file.+- Only a shot LARGE enough to be downscaled gets the pair: `<stem>.full.png` (native) + `<stem>.safe.png` (downscaled). A renderer should prefer `.safe` for display and `.full` for pixel-exact work; when only `<stem>.png` exists, that IS both.++**Janitor (automatic):** the pull cache self-prunes (default: 7-day age cap, 2 GB size cap, 4000-file cap, oldest deleted first, newest always kept; a shot's sidecar follows its PNG on delete). No cleanup is needed caller-side. Inspect with `adom-bridge janitor status`; force a sweep with `adom-bridge janitor '{"sub":"run"}'`. Tune with `ADOM_SHOTS_DIR`, `ADOM_SHOTS_MAX_AGE_DAYS`, `ADOM_SHOTS_MAX_GB`, `ADOM_SHOTS_MAX_FILES`, `ADOM_JANITOR=0`.++---++## 6. The sidecar schema — `<stem>.json` next to every shot++Every pulled shot gets a `<stem>.json` sidecar (a full+safe pair shares ONE sidecar). **This is the self-describing record a visualizer should read instead of parsing the response envelope.** Two shapes, distinguished by `kind`:++**Top-level shot** (a window's parent image, or a full-desktop grab):+```jsonc+{+  "source": "desktop_screenshot_window",     // the verb that produced it+  "timestamp": "2026-07-15T01:14:16.937Z",   // RFC3339 UTC+  "kind": "window",                          // "window" | "screen"+  "hwnd": 986710,                            // null for a "screen" grab+  "title": "KiCad 8.0 — myboard.kicad_pcb",  // window title (null for screen)+  "full": { "path": ".../window/<stem>.full.png", "w": 3840, "h": 2160, "bytes": 402931 },+  "safe": { "path": ".../window/<stem>.safe.png", "w": 1568, "h": 882, "bytes": 88104 },+  //  (when the shot was under the cap, full.path == safe.path == the single <stem>.png)+  "coordMap": { "shotId": "...", "image": {...}, "screenRect": {...}, "dpiScale": 1.5, "imageToScreen": {...} },+  "windowRect": { "x": 100, "y": 80, "w": 3840, "h": 2160, "monitor": 1 }  // null for a screen grab+}+```++**Owned-popup shot** (each child dialog of a window capture):+```jsonc+{+  "source": "desktop_screenshot_window",+  "timestamp": "2026-07-15T01:14:16.980Z",+  "kind": "owned_popup",+  "parent": "2026-07-15T01-14-16.937-986710",  // the parent shot's stem — links child -> parent+  "popupIndex": 1,                              // 1-based; matches the .popup-01 filename tag+  "hwnd": 265518,+  "title": "Error",+  "shotId": "shot_pop1",+  "full": { "path": ".../window/<parentStem>.popup-01.full.png", "w": 420, "h": 180, "bytes": 12043 },+  "safe": { "path": ".../window/<parentStem>.popup-01.safe.png", "w": 420, "h": 180, "bytes": 12043 },+  "coordMap": { "shotId": "shot_pop1", ... },+  "rect": { "x": 900, "y": 500, "w": 420, "h": 180, "monitor": 1 }  // the popup's own screen position+}+```++**How a renderer groups a capture from disk alone (no response envelope needed):**+1. List `<shots_dir>/window/` and `<shots_dir>/screen/`, newest-first (filenames sort chronologically).+2. A file with NO `.popup-NN` tag is a parent (or a standalone window/screen shot); read its `<stem>.json`.+3. Files sharing that stem with `.popup-01..NN` are its owned dialogs — their sidecars carry `parent` + `popupIndex` so you can render them as a labeled child gallery under the parent.+4. For a `screen/` shot, read `display`-equivalent context from `desktop_list_monitors` (the sidecar carries the shot's own rect; the live monitor map is the verb) to draw monitor boundaries.+5. Prefer `safe.path` for thumbnails/inline display, `full.path` for a zoom/pixel-exact view; if `full.path == safe.path`, there is a single file.++---++## 7. Driving without disturbing the user++Capture is background by default (PrintWindow, no focus steal, no cursor move). To also ACT without foregrounding:++- `desktop_find_control {hwnd, name|contains, role?}` then `desktop_ui_click` / `desktop_ui_set` — background Invoke / SetValue by accessible name. Add `scope:"popups"` to target a control inside an owned dialog.+- Coordinate clicks (`desktop_click {space:"image", shotId, x, y}`) as the fallback when a control is not in the UIA tree (some custom-drawn / shadow-DOM controls are not).+- `desktop help background` lists exactly which verbs run in the background vs which foreground the window.++---++## Related++- `desktop_find_window {titleContains|className}` — resolve an hwnd (topmost match wins; no racy list-diffing).+- `desktop_list_windows` — enumerate all top-level windows with hwnds + rects.+- `desktop_list_monitors` — the authoritative monitor map (physical + logical bounds, scale, primary).+- `desktop_screenshot_screen` — full virtual-screen grab (all monitors, stitched).+- `desktop_record_window_start` / `desktop_record_screen_start` — background video capture (same PrintWindow/WGC family).+- `adom-bridge janitor status` — verify the auto-pull cache is being managed (so a tool never builds its own cleaner).

@@ -0,0 +1,108 @@+---+name: adom-bridge-window-identity+description: Make a window an AI drives present itself as YOUR app on Windows — its taskbar button, Alt-Tab entry, hover name, jump-list (right-click menu), taskbar overlay badge, and pins. Covers the AUMID model, the register+stamp two-halves rule, per-session identities, jump-list tasks + header branding, taskbar progress/overlay, and the icon-format rules (why an icon renders as a generic white document and how to fix it). Use when a bridge borrows a host window (e.g. Chrome for Testing) and it reads as the wrong app.+---++# Window identity and the taskbar — Adom Bridge's AUMID verbs++This is an advanced corner of the Windows shell that few APIs expose cleanly. Adom Bridge (ab) wraps it in a small, **generic** verb family: you pass a name + icon + (optionally) a command, and ab makes any window — even one owned by another process — present itself as *your* app across every shell surface. ab knows nothing about which app you are; it applies what you pass.++The motivating case: a bridge drives a **Chrome for Testing** window, which otherwise reads *"Test"* with Chrome's icon in the taskbar and Alt-Tab — two brands and a confusing word. These verbs make it read as your bridge instead.++## The one concept you must hold: the AUMID++Windows groups and labels windows by their **Application User Model ID** (AUMID) — a short dotted string like `Adom.Pup.session42`. The AUMID is what the shell resolves to get:++- the **taskbar button** grouping, its **icon**, and its **name**+- the **Alt-Tab** entry (icon + name)+- the **jump list** (the right-click menu on the taskbar button) and its **header row** (the app tile above *Pin to taskbar* / *Close window*)+- **toasts** you raise, and how a user **pins** the window++A window has *some* AUMID whether you set one or not (it inherits the owning process's). Your job is to (1) give the window a **specific** AUMID and (2) tell Windows what that AUMID **means** (its name + icon). Those are two different operations — miss either and the identity is half-wrong.++## The two halves — you need BOTH++| Half | Verb | What it does |+|---|---|---|+| **Stamp the window** | `desktop_set_window_identity {hwnd, appId, iconPath, displayName, relaunchCommand}` | Puts the AUMID on the *live* HWND (`PKEY_AppUserModel_ID`) + sets the title-bar/Alt-Tab icon (`WM_SETICON`) + the Relaunch trio for the jump-list header. |+| **Register the AUMID** | `desktop_register_app_identity {appId, displayName, iconPath, shortcut?}` | Teaches Windows what that appId *means*: an HKCU `AppUserModelId\<appId>` key (name + icon) and, when `shortcut:true`, a Start Menu shortcut carrying the AUMID (what makes it **pinnable**). |++Stamp without register → Alt-Tab / the taskbar fall back to the owning exe's icon (the "Test / Chrome icon" problem). Register without stamp → nothing points the window at your AUMID. **Do both.**++`desktop_unregister_app_identity {appId}` removes the registration (HKCU key + any Start Menu shortcut carrying that AUMID) — call it when a per-session identity is done.++Everything here is **HKCU only** — no elevation, no UAC prompt, ever.++## Per-session identities (`shortcut:false`)++For a window that comes and goes (one browser session), you want a **distinct** AUMID per window so each keeps its own taskbar button, but you do NOT want a Start Menu shortcut per session (that would spray dead entries). Register with `shortcut:false`:++```+desktop_register_app_identity {appId:"Adom.Pup.session42", displayName:"Adom Pup", iconPath:"C:\\...\\pup.ico", shortcut:false}+desktop_set_window_identity   {hwnd:<cft hwnd>, appId:"Adom.Pup.session42", iconPath:"C:\\...\\pup.ico", displayName:"Adom Pup", relaunchCommand:"<how to reopen>"}+```++Registry-only registration gives Alt-Tab + taskbar hover the right name + icon with no top-level Start Menu entry. Pair every `shortcut:false` register with an `unregister` at session close. Such an identity is **not pinnable** (no shortcut) — keep a separate shortcut-mode registration for a launcher identity you want users to pin.++**The anchor (ab 2.1.47, wiki #155).** A registry-only identity with NO shortcut anywhere makes the shell resolve the AUMID lazily on the first right-click of its taskbar button: the jump list paints, dismisses ~300 ms later, and only the second right-click stays. Measured with a timed harness over 26 fresh AUMIDs; a hidden `.lnk`, `SHAddToRecentDocs(SHARD_APPIDINFO)`, a warmed task shim, a 30 s settle and a no-list registration all still flash; a VISIBLE `.lnk` carrying the AUMID, in the Programs root or in a subfolder, is the one fix. `anchor:true` (opt-in; default OFF since 2.1.49) writes a small visible anchor `.lnk` inside one Start Menu subfolder (`anchorFolder`, default "Adom Bridge"): N per-window identities show as ONE collapsed folder. Its target is the windowless `ab-taskrun.exe` shim (a Start click does nothing), the response carries `anchorPath` and `mode:"registry-only+anchor"`, and `unregister` removes it (folder too, once empty; pass the same `anchorFolder` if you named one). Why off by default: the anchor is a real Start Menu entry (it shows under All apps, in "Recently added", and in search; `NoStartPage` on the target exe does not hide it from search), and John's rule is a clean Start Menu over a first-click flyout. The flash is the accepted cost of the default.++## Jump lists — the right-click menu + its header++`desktop_set_window_jumplist {appId, tasks, hwnd?, headerIcon?, headerCommand?, headerName?}` attaches a custom right-click menu to the AUMID. Each task: `{title, target?, args?, iconPath?, description?}` (target defaults to ab's bundled CLI, so a task can just be a verb + JSON). `tasks:[]` clears the list.++- Tasks appear on the taskbar right-click menu of **every** window stamped with that AUMID, so a per-session appId gives a per-window menu.+- **The header row** (the app tile above Pin/Close) is a *separate* surface. It is painted from the **window's Relaunch trio**, not the AUMID registry icon — so a `shortcut:false` AUMID shows a generic icon there unless you brand it. Pass `hwnd` + `headerIcon` (and optionally `headerCommand`/`headerName`) and ab stamps the window's Relaunch trio so the header renders your icon **without** a Start Menu shortcut. `headerBranded:true` in the response confirms it stuck.++## Taskbar status — progress + overlay badge++`desktop_taskbar {hwnd, progress?, overlay?, flash?}` paints **glanceable status** on any window's taskbar button (works cross-process), so you can show what the AI is doing on the real app window it drives:++- `progress:{state:"normal"|"paused"|"error"|"indeterminate"|"none", value?}` — a colored bar (green / yellow = human-in-the-loop like a captcha / red / marquee).+- `overlay:{badge:"adom"|"none", icon?:<.png/.ico path or base64>, avatar?, tooltip?}` — a small badge in the button corner. For Chrome/Edge, that overlay slot holds the **profile avatar**; pass `avatar` and ab composites your mark onto it so the user keeps work-vs-personal.+- `flash:"until_focused"|"count"|"stop"` — flash the button for attention.++`desktop_flash_window` is the lightweight flash-only cousin.++## Toasts++`notify_user` raises a native Windows toast under ab's own identity (AUMID `inc.adom.bridge`, the Adom logo). See the `adom-bridge-notify` skill for the full toast catalog (progress, sticky reminders, buttons that round-trip a click).++## Icon formats — why an icon renders as a generic white document++This is the #1 source of "my icon doesn't show." The identity verbs return an **`iconCheck`** block that inspects the file you passed and lists concrete problems. The rules it encodes:++- **Give a multi-size `.ico`** (16 / 24 / 32 / 48 / 256). A single-size icon looks bad where the shell wants a different size.+- **The 256×256 size MUST be PNG-compressed.** Since Windows Vista, a 256px `.ico` entry stored as an uncompressed BMP/DIB renders as the **generic white-document icon** on the jump-list header and taskbar. This is subtle: the icon looks fine in an image viewer but wrong in the shell. Re-export the `.ico` with the 256px size PNG-compressed (most icon tools do this; if unsure, drop the 256px size). `iconCheck` flags this specifically.+- **A per-window `RelaunchIconResource` (the jump-list header) for a `.ico` uses a BARE path** — ab handles this; you just pass the `.ico`. A stray `path,0` (the PE-resource form) breaks a `.ico`, because the shell then looks for "resource index 0 of a PE module," which a `.ico` is not → generic icon. (This was a real bug, fixed ab 1.9.151.)+- **A PE module (`.exe`/`.dll`) is referenced as `<path>,<index>`.** ab uses `,0`; pass your own index if your icon isn't resource 0. A standalone `.ico` is simpler.+- **SVG does not work** — the Win32 shell can't load it. Convert to `.ico`/`.png`.+- **The AUMID registry icon (taskbar/Alt-Tab) accepts `.ico` or `.png`; an `.exe` path there renders the blank-doc icon.** A taskbar **overlay** wants a small (~16px) image; a `.png` is ideal (ab converts it to `.ico` internally).++If `iconCheck.ok` is false, fix the file per `iconCheck.issues` and re-stamp — don't ship the broken icon.++## The live-tile trap (the one timing gotcha)++Re-stamping the **same** appId on a **live** window with a new icon updates the title bar + Alt-Tab but **not** the taskbar tile: Win11 bakes the tile when the button is *created* and never re-reads it (WM_SETICON, ITaskbarList DeleteTab+AddTab, SHChangeNotify, RedrawWindow — all measured no-ops). The only non-disruptive way to change a live tile is to make the shell create a **new** button: register a **different** appId (registry-only, new icon) and stamp the window with it — the button is destroyed and recreated with the new tile in ~1s, no window flicker. Cost: a pin made under the old appId shows the running window as a separate button, so use a **stable** appId for identity you want pinnable and a **varying** one only when the tile must track state.++## Recipe: brand a borrowed window end-to-end++```+# 1. Teach Windows the identity (once per install for a stable id; per session for shortcut:false)+desktop_register_app_identity {appId:"MyBridge.Session7", displayName:"My Bridge", iconPath:"C:\\bridge\\icon.ico", shortcut:false}++# 2. Stamp the live window (taskbar + Alt-Tab + title bar) and brand the jump-list header (Relaunch trio)+desktop_set_window_identity {hwnd:<hwnd>, appId:"MyBridge.Session7", iconPath:"C:\\bridge\\icon.ico", displayName:"My Bridge", relaunchCommand:"mybridge --reopen 7"}++# 3. Attach a right-click menu (optional) + brand its header row+desktop_set_window_jumplist {appId:"MyBridge.Session7", hwnd:<hwnd>, headerIcon:"C:\\bridge\\icon.ico",+                             tasks:[{title:"New tab", args:"browser_open_window {}"}]}++# 4. Show live status on the button while you work (optional)+desktop_taskbar {hwnd:<hwnd>, overlay:{badge:"adom", tooltip:"My Bridge is driving"}, progress:{state:"indeterminate"}}++# 5. On session close+desktop_taskbar {hwnd:<hwnd>, progress:{state:"none"}, overlay:{badge:"none"}, flash:"stop"}+desktop_unregister_app_identity {appId:"MyBridge.Session7"}+```++Resolve `<hwnd>` with `desktop_list_windows` / `desktop_find_window`.

@@ -0,0 +1,163 @@+---+name: adom-bridge-windows-host+user-invokable: false+description: "Read this BEFORE doing any work on adom-bridge from a Claude Code session running directly on the user's Windows machine. Explains how to route everything through the adom-bridge CLI so paths, file operations, and process spawns reach the user's real filesystem instead of getting silently virtualized into Claude Code's Windows AppContainer sandbox. Skipping this causes hour-long debugging spirals where 'open install folder' fails, bridges install to the wrong place, screenshots come back blank, and synthesized clicks don't reach the WebView2."+---++# Working on adom-bridge from Claude Code on Windows++This skill applies when Claude Code is running **on the user's Windows machine** — i.e. you have a `bash`/`PowerShell` tool that hits the local filesystem directly, instead of running inside the Adom Docker container.++## The single most important fact++Claude Code on Windows runs inside a **Windows AppContainer sandbox**. Every filesystem write from your `bash` or `PowerShell` tool gets transparently redirected:++| What you write | Where it actually lands |+|---|---|+| `C:\Users\john\AppData\Local\Adom Bridge\...` | `C:\Users\john\AppData\Local\Packages\Claude_<pkgid>\LocalCache\Local\Adom Bridge\...` |+| `C:\Users\john\Documents\...` (any AppData/user-roaming write) | The Packages\Claude_<pkgid>\LocalCache equivalent |++**From your perspective both paths show identical contents.** The redirect is invisible inside the sandbox. From the user's real filesystem (their explorer.exe, their PowerShell from Start menu), only the `Packages\Claude_<pkgid>\...` location exists.++**Consequence:** If you launch the GUI from your `bash` (`start "" "C:\...\adom-bridge.exe"`), the GUI inherits your AppContainer. Bridges it installs land in the virtualized cache. The user clicks "Open install folder" and Explorer says **"Location is not available"** because the path the GUI wrote into the registry doesn't exist in the user's real session.++This is the entire reason "Open install folder" took an hour to ship in v1.8.11. Don't repeat it.++## The fix: drive the GUI through `adom-bridge` CLI like Docker does++Instead of using your own `bash`/`PowerShell` for anything user-visible, route every operation through the `adom-bridge` CLI. The CLI talks to a relay (HTTP) which dispatches to the running GUI (WS). The GUI executes commands in **its own process context** — which, when launched correctly, is the user's normal Windows session, unsandboxed.++### Setup (do this once per session)++1. **Pick alt ports if 8765/8766 are taken.** Docker Desktop typically holds `8765` and `8766` for its internal use. Check with `netstat -ano | grep -E ":876[56] "`. Use `8865`/`8866` (or any free pair).++2. **Start the local relay on the alt ports:**+   ```bash+   nohup C:/Github/adom-bridge/cli/target/release/adom-bridge-cli.exe serve \+     --http-port 8866 --ws-port 8865 > /tmp/relay.log 2>&1 &+   ```+   Verify: `cat /tmp/relay.log` should show `Adom relay server started`.++3. **Add the alt-port localhost server to `~/.adom/config.json`** so the GUI auto-connects on launch:+   ```json+   {+     "auth_token": "<your-token>",+     "auto_connect": true,+     "enabled": true,+     "id": "local-dev-server",+     "name": "localhost",+     "url": "ws://localhost:8865"+   }+   ```+   (Edit the existing `localhost` entry if it's already there — just enable it and bump the port.)++4. **Launch the GUI via `cmd /c start ""`** — this routes through the Windows Shell broker, which spawns the new process in the user's normal session, breaking your AppContainer inheritance:+   ```bash+   cmd //c start "" "C:\Users\john\AppData\Local\Adom Bridge\adom-bridge.exe"+   ```+   **DO NOT** use bare `start "" "..."` from your bash — that inherits your sandbox.++5. **Set `ADOM_API` env var** so the CLI hits your alt port:+   ```bash+   export ADOM_API="http://127.0.0.1:8866"+   ```+   Pin this near the top of every command sequence; it doesn't persist across shells.++6. **Verify the GUI is unsandboxed.** Run via shell_execute and check the token:+   ```bash+   adom-bridge shell_execute '{"command":"powershell -NoProfile -ExecutionPolicy Bypass -Command \"Add-Type -TypeDefinition @\\\"using System; using System.Runtime.InteropServices; public class T { [DllImport(\\\\\\\"advapi32.dll\\\\\\\")] public static extern bool OpenProcessToken(IntPtr p, int a, out IntPtr t); [DllImport(\\\\\\\"advapi32.dll\\\\\\\")] public static extern bool GetTokenInformation(IntPtr h, int c, IntPtr b, int l, out int r); [DllImport(\\\\\\\"kernel32.dll\\\\\\\")] public static extern IntPtr GetCurrentProcess(); }\\\"@; $t=[IntPtr]::Zero; [void][T]::OpenProcessToken([T]::GetCurrentProcess(), 8, [ref]$t); $b=[Runtime.InteropServices.Marshal]::AllocHGlobal(8); $l=0; [void][T]::GetTokenInformation($t, 29, $b, 8, [ref]$l); Write-Host TokenIsAppContainer=$([Runtime.InteropServices.Marshal]::ReadInt32($b))\"","timeout_secs":5}'+   ```+   Expect `TokenIsAppContainer=0`. If it returns `1`, you launched the GUI from a sandboxed parent — kill it and relaunch via `cmd //c start ""`.++### Everything you do from here goes through the CLI++| Need to... | Use this | NOT this |+|---|---|---|+| Run PowerShell on user's machine | `adom-bridge shell_execute '{"command":"powershell ...","timeout_secs":N}'` | Your own `PowerShell` tool |+| Screenshot a window | `adom-bridge desktop_screenshot_window '{"hwnd":N}'` | Win32 `PrintWindow` from your PowerShell |+| Screenshot the screen | `adom-bridge desktop_screenshot_screen` | Your own screen capture |+| Find windows | `adom-bridge desktop_list_windows` | UIA enumeration from your PowerShell |+| Install/uninstall a bridge | `adom-bridge bridge_install`, `bridge_uninstall` | Manually copying zip contents to the cache dir |+| Inspect the bridge registry | `adom-bridge bridge_list` | Reading `bridge.json` from disk paths |+| Open a folder in Explorer | (test by invoking the same Rust code path; see below) | `Start-Process explorer.exe` from your bash |++**Quoting trick for `shell_execute`:** the JSON arg gets parsed once, then PowerShell parses it again. Backslashes need quadrupling (`\\\\` for a literal `\`). When the command is non-trivial, **write it to a `.ps1` file and `shell_execute` the file** instead of inlining:+```bash+cat > /c/tmp/probe.ps1 << 'EOF'+# ... powershell here, single-quoted heredoc so no shell interpolation+EOF+adom-bridge shell_execute '{"command":"powershell -NoProfile -ExecutionPolicy Bypass -File C:\\\\tmp\\\\probe.ps1","timeout_secs":10}'+```++## Specifically: opening folders in Explorer++This is the one that took TWO hours across multiple iterations. Lessons crystallized:++1. **`explorer.exe /select,<path>`** — the only reliable form. Opens a NEW Explorer window navigated to the path's parent, with the path itself pre-selected. Use this in `open_path_in_explorer`-style Tauri commands.+2. **`explorer.exe <path>` (no flag)** — silently no-ops when an Explorer process is already up. Don't use.+3. **`ShellExecuteW("open", <path>)`** — returns success (HINSTANCE > 32) but often doesn't visibly open a window. Don't use for folders.+4. **`cmd /c start "" "<path>"`** — same fate as #2 for folders. Fine for URLs (used by `open_external_url`).++### The `raw_arg` trap++`std::process::Command::new("explorer").arg("/select,C:\\path with space\\hello").spawn()` does **NOT** work. Rust auto-wraps any arg containing spaces in double quotes, emitting:++    explorer.exe "/select,C:\path with space\hello"++Explorer parses the whole quoted string as one token, fails to match `/select,`, and falls back to opening the user's Documents folder. The user reports "Open install folder takes me to Documents."++What Explorer actually wants:++    explorer.exe /select,"C:\path with space\hello"++— quotes around the **path portion only**, not the whole arg. The fix is `std::os::windows::process::CommandExt::raw_arg`, which emits the literal command-line bytes without Rust's escaping rules:++```rust+use std::os::windows::process::CommandExt;+let raw = format!(r#"/select,"{}""#, win_path);+std::process::Command::new("explorer").raw_arg(&raw).spawn()?;+```++**General rule**: when invoking a Windows exe with a quirky / legacy command-line parser (`explorer`, `msbuild`, `cl`, some `cmd` builtins), assume `Command::arg` will mis-quote. Use `raw_arg` and construct the command line by hand. You can verify the emitted command line via `shell_execute` running a PowerShell simulation:++```powershell+$psi = New-Object System.Diagnostics.ProcessStartInfo+$psi.FileName = "explorer.exe"+$psi.Arguments = '/select,"' + $path + '"'   # ← matches raw_arg output+$psi.UseShellExecute = $false                 # ← matches Rust's CreateProcessW path+[void][System.Diagnostics.Process]::Start($psi)+```++Then enumerate `(New-Object -ComObject Shell.Application).Windows()` to see what location Explorer actually navigated to. If it's the path you wanted: ship. If it's `Documents` / `Home`: your quoting is wrong.++Before passing the path to explorer, normalize:+- Replace `/` with `\` — `BridgeRegistry` stores cache paths with forward slashes via `dirs::data_local_dir()`.+- Strip `\\?\` prefix — Tauri's `resource_dir()` returns paths in this verbatim form for bundled bridges; Explorer rejects it.++**Always check the path exists BEFORE shelling out**, and return a structured error if it doesn't. The Rust side:+```rust+if !p.exists() {+    return Err(format!("Path does not exist: {}", path));+}+```+catches the sandbox-write-to-wrong-place class of bugs early. If you see this error, you almost certainly installed the bridge while your GUI was sandboxed; reinstall via the CLI-driven user-session GUI.++## Debugging checklist when something "doesn't work"++If a user-visible action (open folder, screenshot, bridge install) seems broken, before iterating on the Rust code:++1. **Is the GUI unsandboxed?** Run the TokenIsAppContainer probe above. If `1`, the entire path is poisoned — relaunch via `cmd //c start ""` and reinstall any cache state.+2. **Are you using `ADOM_API=http://127.0.0.1:8866`?** If your CLI hits the default 8766 and Docker has it, you get `Connection Failed`.+3. **Does the path EXIST on the user's real filesystem?** Use `shell_execute` to run `Get-ChildItem <path>` — that's the source of truth. Don't trust `ls` from your own bash.+4. **Did `taskkill /F /IM adom-bridge.exe` collateral-kill the relay?** The CLI binary and the GUI binary share the same exe name. Kill by PID, not by image name, so the relay survives.+5. **Are you reading explorer's view via COM?** Explorer.exe caches folder listings aggressively and can show stale state. Trust `Get-ChildItem` (kernel API) over `Shell.Application.Windows().Document.Folder.Items()` (cached UI view) — the FS API is the truth.++## Why this gets re-learned every session++Every Claude on the Windows host starts in the sandbox without knowing it. Path operations *appear* to work — your `Test-Path` returns True, your `ls` shows files. The redirect is invisible until something user-visible (Explorer, another non-sandboxed process) tries to use the same path and finds it missing.++Read this skill at session start when you're working on adom-bridge locally. It saves an hour.++## Related memory++- `~/.claude/projects/C--Github-adom-bridge/memory/feedback_dont_kill_gui_during_iter.md` — don't kill the GUI repeatedly during iteration. The CLI-driven approach above means you almost never *need* to kill the GUI: changes that don't touch Rust ship without a rebuild via `release-bridge.sh`, and changes that do touch Rust use FAST tauri (~1-2 min) with a single GUI restart.

@@ -0,0 +1,2282 @@+---
+name: adom-bridge
+description: Use when the user wants to send files to their desktop, control KiCad or Fusion 360, send desktop notifications, or troubleshoot the desktop connection. Provides CLI tools for bridging the Docker container to the user's local machine.
+---
+
+# Adom Bridge
+
+Bridge between Claude Code (running in an Adom Docker container) and the user's desktop applications via WebSocket.
+
+> **The CLI is `adom-bridge`** (renamed from `adom-bridge-cli` in v2.0.33 — the `-cli` was noise on Linux). Use `adom-bridge <verb>`. The old `adom-bridge-cli` name still works (the pkg links both), so existing scripts don't break — but prefer `adom-bridge` going forward. On Windows the CLI file stays `adom-bridge-cli.exe` (the GUI app owns `adom-bridge.exe` there).
+
+**Install surface:** the canonical install page is `apps/adom-bridge` on the Adom wiki — it hosts the Linux CLI (`docker_binary`), the Windows installer (`.exe`), and the four sibling skills (pup, kicad-bridge, fusion-bridge, + this one). The gallia `adom-bridge-discovery` skill surfaces this page on any related user query. `adom-bridge setup_desktop` also returns a dynamic installer URL pulled from the latest GitHub release.
+
+**First-time setup?** If the user hasn't installed the desktop app yet, see the Setup section below to walk them through downloading, installing, and connecting the app.
+
+Quick check if desktop is connected:
+```bash
+adom-bridge ping
+```
+
+**Companion skills** (installed alongside this one from the wiki):
+- `adom-bridge-kicad` — KiCad bridge: launch editors, open designs, install libraries, run DRC, window capture + keyboard/click automation (`plugins/kicad/SKILL.md`)
+- `adom-bridge-fusion` — Fusion 360 bridge: launch, open designs, STEP/GLB/.lbr import-export, BOM + API queries, Fusion screenshots (`plugins/fusion360/SKILL.md`)
+- `pup` — browser automation (Puppeteer-style): open URLs, screenshot, eval JS, multi-session Chrome (`gallia/skills/pup/SKILL.md`)
+
+## How It Works
+
+```
+Claude Code -> adom-bridge <command> -> Relay Server (HTTP :8766) -> WebSocket :8765 -> Adom Bridge App -> KiCad / Fusion 360 / Browser / Shell
+```
+
+The `adom-bridge` binary is a single Rust CLI that does everything:
+- `adom-bridge serve` -- Start the relay server (WebSocket :8765 + HTTP API :8766)
+- `adom-bridge <command> '<json>'` -- Send commands to the desktop app via the running relay
+
+The relay server runs in the Docker container. The Adom Bridge app runs on the user's PC and connects via WebSocket.
+
+## Starting the Relay Server
+
+The relay must be running before the desktop app can connect. **In a container, start it SUPERVISED** (v1.9.168+):
+
+```bash
+adom-bridge serve --supervise
+```
+
+**Why not `adom-bridge serve &`?** A backgrounded (`&`) relay is still a child of your shell/session. When your session is torn down (you finish, or the container reaps it), the relay dies with it — and then every connected desktop hits HTTP 500 on `/proxy/8765/` and loops "Reconnecting in 30s" **for hours** until a human restarts it (wiki issue #24, hit live 2026-07-23). `--supervise` **detaches the relay into its own session (reparented to init)** so it survives your session, and starts a watchdog that:
+- restarts the relay with **exponential backoff** (2s → … → 5 min cap; a clean run resets it — a broken relay is never bludgeoned), and
+- **toasts the connected desktops on every restart** with the reason from the relay log, so the owner finds out something went wrong.
+
+```bash
+adom-bridge serve --supervise            # detached + self-healing (use this in containers)
+adom-bridge serve --supervise --owner AdomLapper   # send restart toasts to one desktop
+adom-bridge serve --stop                 # stop the watchdog + relay
+```
+
+`serve` (plain, foreground) still works and prints a loud hint telling you it will die with the session — fine for a quick local relay you'll sit and watch. **Caveat:** a full CONTAINER REBOOT still needs a boot hook (cron `@reboot` / the container's init); the watchdog covers session teardown, not host reboot.
+
+This starts:
+- WebSocket server on `0.0.0.0:8765` (desktop app connects here)
+- HTTP API on `127.0.0.1:8766` (CLI commands go here)
+
+Check if it's running:
+```bash
+curl -sf http://127.0.0.1:8766/health
+```
+
+## First-Time Setup (Install & Connect)
+
+**You are running on a Docker container. You have NO access to the user's desktop.** Guide them step-by-step, ask questions, wait for answers, and verify each step.
+
+> **As soon as you're connected, run `adom-bridge sync_skills` (v1.9.37+).** Installing the
+> adom-bridge core pkg gives you only CORE skills — it does NOT give you a DYNAMIC/cloud
+> bridge's skill (kicad, fusion, blender, any third-party). `sync_skills` runs `bridge_list`
+> and installs each bridge's own skill pkg into `~/.claude/skills/`, so you can actually
+> discover + drive whatever bridges THIS desktop has. (The CLI also runs this automatically
+> once/day in the background, but doing it on connect makes the bridge skills available to
+> the current session immediately.) Re-run it any time the desktop gains a bridge;
+> `adom-wiki pkg update` keeps them fresh.
+
+### Step 1: Check if already connected
+
+```bash
+adom-bridge ping
+```
+
+If this returns `{ "status": "connected" }`, the desktop is already set up -- skip to "Verify the connection" below. If it errors, continue.
+
+### Step 2: Ensure the relay is running
+
+```bash
+curl -sf http://127.0.0.1:8766/health
+```
+
+If not running (in a container, ALWAYS use `--supervise` so it survives your session): `adom-bridge serve --supervise`
+
+### Step 3: Ask what OS they use
+
+Ask the user: **"What operating system is your desktop/laptop? (Windows, Mac, or Linux)"**
+
+- **Windows 10/11** -- proceed
+- **macOS / Linux** -- "Support is coming soon. The desktop app currently only runs on Windows."
+
+### Step 4: Install & connect
+
+Run `adom-bridge setup_desktop` — it auto-detects this container's relay URL and returns a ready-to-run **`register_command`**, a fallback `server_config` JSON, and the `installer_url`. Prefer the zero-paste path:
+
+---
+
+**Option 0: Zero-paste via your Adom account (PREFERRED)**
+
+Run the **`register_command`** that `setup_desktop` returned (it's `adom-bridge register_container` with the name + URL filled in). That injects this connection into the **user's Adom cloud profile**. Then the user just:
+1. Installs Adom Bridge (from `installer_url`) and opens it,
+2. **Signs in with their Adom account** (Connections panel → "Sign in to Adom"),
+
+and the connection appears in their list and auto-connects — **no JSON paste at all**. This is the modern path and the one to try first. (`register_container` needs an Adom cloud container — it uses the mounted account token — and returns `ok:false` on a non-Adom box; if so, use Option A/B below.)
+
+**Already-running desktop? `server_sync` (v1.9.215+).** A signed-in ab reads the cloud profile at boot, at sign-in, and hourly — and `adom-bridge server_sync` (optionally `--target <name>`) makes it re-read RIGHT NOW. The merge is cloud-wins, whole entry including `authToken`. So the flow for adding a server or **rotating a relay token** on live desktops is: update the cloud key (`register_container` writes them) → `server_sync` per desktop → verify with `server_list`. Do NOT use `server_remove` + `server_add` for rotation — removing the entry you are talking through severs your own transport (wiki #387).
+
+---
+
+**Option A: Automatic setup via Claude Code (paste fallback)**
+
+If you have **Claude Code** or **Claude Desktop** on your laptop, paste this prompt:
+
+> Install Adom Bridge and connect it to my cloud container. (Most users instead get Adom Bridge bundled with Hydrogen, which installs and connects it for them; use this prompt when you are driving the desktop from a cloud container.) Download the installer from `<installer_url>`, run it silently, then write this JSON to `%USERPROFILE%\.adom\config.json`:
+> ```json
+> {"servers":[<server_config JSON>]}
+> ```
+> Then launch "Adom Bridge" from the Start Menu.
+
+*(Replace `<installer_url>` and `<server_config JSON>` with the actual values from `setup_desktop`.)*
+
+**Option B: Manual setup**
+
+1. Download the installer: **[<installer filename>](<installer_url>)**
+2. Run it and follow the prompts — the app installs to the Start Menu as "Adom Bridge"
+3. Open **Adom Bridge** from the Start Menu
+4. Paste this JSON into the text field that says **"Paste server JSON to add ..."** and press **Enter**:
+   ```json
+   <server_config JSON>
+   ```
+5. The server will appear and auto-connect
+
+---
+
+Wait for the user to confirm they see a green dot next to the server name before proceeding.
+
+**Important:** Each container has its own relay server. New containers need a new entry -- old entries from previous containers won't work.
+
+### Step 6: Verify the connection
+
+```bash
+adom-bridge ping
+# Expected: { "echo": "pong", "roundTripMs": ..., "status": "connected" }
+
+adom-bridge status
+# Expected: one client with the user's hostname and capabilities
+
+adom-bridge notify_user '{"title":"Hello from Docker!","body":"Your desktop is connected."}'
+```
+
+Tell the user what you see. If `ping` succeeds:
+
+> "Your desktop is connected! I can now send files to your machine, open browser windows for visual debugging, control KiCad and Fusion 360, take screenshots of your desktop, and send you notifications."
+
+### Step 7: Optional -- Node.js for browser features
+
+Ask: **"Would you like to use the visual browser debugging feature? This opens Chrome windows on your desktop that I can control."**
+
+- **Yes + Node.js installed** -- "Great, the browser bridge auto-installs deps on first use."
+- **Yes + no Node.js** -- "Download Node.js from https://nodejs.org (LTS), install it, then restart Adom Bridge."
+- **No** -- skip, they can enable it later
+
+### Common connection issues
+
+| Symptom | Fix |
+|---------|-----|
+| `ping` returns `"No desktop client connected"` | User hasn't added this container in the desktop app yet |
+| Desktop app shows "disconnected" | Check the URL uses `wss://` (not `ws://` or `https://`), port is `8765` |
+| Relay server not running | `adom-bridge serve --supervise` (survives your session; see Starting the Relay Server) |
+| Multiple stale connections | `adom-bridge kick_all` -- app auto-reconnects within seconds |
+| Desktop app not installed | Download from [github.com/adom-inc/adom-bridge/releases](https://github.com/adom-inc/adom-bridge/releases) |
+
+## CLI Tool
+
+```bash
+adom-bridge <command> '<json-args>'
+```
+
+**Examples:**
+```bash
+adom-bridge ping
+adom-bridge status
+adom-bridge pup_open_window '{"sessionId":"dart2","url":"https://example.com"}'
+adom-bridge pup_eval '{"sessionId":"dart2","expr":"document.title"}'
+adom-bridge pup_screenshot '{"sessionId":"dart2"}'
+adom-bridge pup_list_windows
+adom-bridge pup_close_window '{"sessionId":"dart2"}'
+adom-bridge notify_user '{"title":"Hello","body":"From Docker"}'
+adom-bridge shell_execute '{"command":"echo hello"}'
+adom-bridge pull_file '{"filePaths":["C:\\Users\\john\\Downloads\\image.png"],"saveTo":"/tmp"}'
+```
+
+**Output:** JSON to stdout. Screenshots save to `/tmp/adom-bridge-screenshots/` and return the file path.
+
+**Config location:** The desktop app stores server config at `~/.adom/config.json` (`%USERPROFILE%\.adom\config.json`). This is separate from the binary — config survives updates and reinstalls.
+
+## Available Commands
+
+**Get the full structured command list with descriptions, args, and prerequisites:**
+```bash
+adom-bridge commands            # aliases: list_commands, help
+adom-bridge --target <name> commands   # + THAT box's installed bridges (installed_bridges_on_target)
+```
+Returns categorized JSON with every command, its required/optional args, return values, prerequisites, and workflow notes. Run this FIRST when you're unsure what a verb is called.
+
+**Two kinds of verbs (v1.9.103 — don't confuse them):**
+- **BUILT-IN ab-core verbs** are always available on every Adom Bridge, no install, NOT bridges. This is where screenshots, windows, input, files, registry, shell, tunnel, update, and notify live. A whole-screen shot is `desktop_screenshot_screen`; one window (with chrome) is `desktop_screenshot_window {"hwnd":N}` or `{"titleContains":"..."}` (get hwnds from `desktop_list_windows`).
+- **BRIDGE verbs** (`kicad_`/`fusion_`/`pup_`/`blender_`/`nbrowser_`…) need that bridge installed — see `installed_bridges_on_target` in `commands`, or run `bridge_list`.
+
+If a verb returns `errorCode:"unknown_verb"`, **read the error's `_hint`** — it carries a fuzzy "did you mean" (e.g. `desktop_screenshot` → `desktop_screenshot_screen`) and tells you whether the right verb is built-in or a bridge. Don't conclude a capability is "a missing bridge" from a guessed verb name; call `commands` and check.
+
+### Connection Management
+
+- `ping` -- 5s round-trip test. Use BEFORE browser/shell commands to verify the desktop connection is alive.
+- `status` -- Check who's connected, their capabilities, desktop paths, and **app installation status**. The `desktop.apps` object shows:
+  - `kicad.installed` / `kicad.version` / `kicad.bridgeRunning`
+  - `fusion360.installed` / `fusion360.running` / `fusion360.bridgeRunning` / `fusion360.addinInstalled` / `fusion360.addinConnected`
+  - `browser.bridgeRunning`
+- `kick_all` -- Force-disconnect all WebSocket clients. Active Adom Bridge apps auto-reconnect within seconds.
+
+#### Programmatic server registration (v1.8.22+)
+
+Three verbs let external apps (Hydrogen's WSL2 workspace, in particular) register their relay server with adom-bridge without the user pasting JSON into the GUI by hand. Mirrors the GUI's Quick Add bar + connect/disconnect buttons.
+
+- `server_add` -- Upsert a relay server by `name`. If a server with that name already exists, the URL (and optionally authToken) is updated rather than creating a duplicate.
+  ```bash
+  adom-bridge server_add '{"name":"hydrogen-workspace","url":"ws://localhost:8765","autoConnect":true}'
+  # → {ok:true, name, url, id, connected:bool, created:bool, _hint}
+  ```
+  - `name` (required) — dedup key. Repeat calls with the same name are idempotent.
+  - `url` (required) — relay WebSocket URL.
+  - `authToken` (optional) — defaults to a dev token (leave unset unless your relay requires one).
+  - `autoConnect` (optional, default `true`) — connect right after upsert. Set `false` to add the entry without dialling out.
+  - Behavior: same URL + already connected → no churn, returns ok. URL changed + autoConnect=true → disconnect old loop + spawn new one. URL changed + autoConnect=false → disconnect old, leave entry registered but not connected.
+- `server_remove` -- Disconnect (if connected) and delete an entry by name. Returns `{ok, removed:bool, wasConnected:bool}`. Idempotent (removing a non-existent entry returns ok with removed:false).
+  ```bash
+  adom-bridge server_remove '{"name":"hydrogen-workspace"}'
+  ```
+- `server_list` -- Persisted server list with live connection status: `{servers:[{name, url, id, autoConnect, enabled, connected:bool, clientCount:0|1, status}]}`. `status` is the fine-grained `connected | reconnecting | disconnected` state machine value.
+
+Persists to the same `~/.adom/config.json` the GUI uses, so entries survive a GUI restart. The `ws_client` supervisor (runs every 30s inside the GUI) auto-reconnects entries with `autoConnect:true` on next launch.
+
+Hydrogen-style usage:
+```bash
+# At Hydrogen container startup
+adom-bridge server_add '{"name":"hydrogen-workspace","url":"ws://localhost:8765","autoConnect":true}'
+
+# At Hydrogen container shutdown
+adom-bridge server_remove '{"name":"hydrogen-workspace"}'
+```
+
+#### Addressing multiple Adom Bridges on one relay (v1.8.133+)
+
+One relay can have **several** Adom Bridges connected at once — e.g. a laptop and an Azure VM, eventually many. Each ab has a **name** (its `--client-name` / Settings value, defaulting to the OS hostname). The cloud CLI addresses a specific one, or fans out to all:
+
+- `adom-bridge targets` — list connected ABs: `{count, targets:[{name, hostname, version, os, connectedAt}]}`. Discover names here first.
+- `adom-bridge --target <name> <verb>` — route the verb to that ab only. `--target` is a **global** flag (goes before the verb; case-insensitive; matches `clientName`, else `hostname`). `ADOM_TARGET=<name>` sets a default (the flag wins).
+- `adom-bridge --target all <verb>` — fan out to **every** connected ab; returns `{broadcast:true, targets:[...], results:{<name>:<verb-result>}, summary:{total,ok,failed}}`. A per-ab timeout/failure is isolated to that ab's entry.
+
+```bash
+adom-bridge targets
+adom-bridge --target azurevm desktop_screenshot_screen
+adom-bridge --target all hd_status        # every box at once, results keyed by name
+```
+
+**No-target behavior:** with exactly ONE ab connected, no `--target` is needed (back-compat). With MULTIPLE connected and no `--target`, the call FAILS with `{error:"ambiguous_target", connected:[...], _hint}` (exit 1) — it won't guess which box. A bad name → `{error:"target_not_found", requested, connected:[...]}` (exit 1). Set each ab's name with the `--client-name <name>` launch flag (Hydrogen passes this when spawning the embedded ab), the Settings field, or `config.json` `client_name`. Full design + the relay-routing internals: [`skills/MULTI_AB_ADDRESSING.md`](MULTI_AB_ADDRESSING.md).
+
+#### Direct HTTP API for sibling apps (v1.8.25+)
+
+If you're authoring a sibling Tauri app on the same machine (Hydrogen, or any future "Adom-family" app), you can skip the CLI binary entirely and POST commands straight into the running adom-bridge GUI on `127.0.0.1:47200` (was `127.0.0.1:8770` through v1.8.32 — moved to be a better neighbor to Hydrogen on 47080+ and avoid the 8000-range collision risk). The endpoint runs inside the GUI process (loopback-only bind), uses the same dispatcher the WS path uses, and returns the same JSON shape as `adom-bridge <verb>` — including every `_hint` field.
+
+| Method | Path | Body | Returns |
+|---|---|---|---|
+| `GET` | `/health` | — | `{"ok":true,"service":"adom-bridge"}` cheap probe |
+| `GET` | `/status` | — | service banner + version + schema + `directApi.cliRequired` list |
+| `POST` | `/command` | `{"app":"<ns>","command":"<verb>","args":{...}}` | The verb's normal payload (200 OK), or `{error, errorCode, _hint}` (4xx/5xx) |
+
+**v1.8.33+ port discovery (sibling apps READ THIS):** Don't hardcode 47200. The GUI may have bound to 47200-47209 instead if the default port was taken (zombie socket, dev instance, third-party collision). Discovery protocol:
+
+1. Read `~/.adom/direct-api-port` (Windows: `%USERPROFILE%\.adom\direct-api-port`) — single-line `host:port`, written by the GUI at bind time, removed at graceful shutdown
+2. If file missing or its port doesn't `/health`, scan `127.0.0.1:47200..=47209` for any port answering with `{"ok":true,"service":"adom-bridge"}`
+3. Validate `service == "adom-bridge"` to disambiguate from other apps that might bind a port in our range
+
+The CLI does this automatically (see `cli/src/direct_probe.rs`). For sibling-app Rust code, see [`skills/DIRECT_API.md`](DIRECT_API.md) for a copy-paste-ready helper.
+
+**Per-verb timeouts (v1.8.31+):** the direct API's command-timeout is no longer a hardcoded 120s — it mirrors the CLI dispatcher's per-verb table (`walk_cloud_tree`/`search_cloud_files`=620s; heavy exports=320s; `bridge_install`/`fusion_start`=300s; default=120s). Caller can override via `args.timeout` (seconds, clamped to 1800).
+
+Example — programmatic server registration without the CLI:
+
+```bash
+curl -X POST http://127.0.0.1:47200/command \
+  -H 'Content-Type: application/json' \
+  -d '{"app":"desktop","command":"server_add","args":{"name":"hydrogen-workspace","url":"ws://localhost:8765","autoConnect":true}}'
+# → identical JSON to `adom-bridge server_add '{...}'`, including the _hint
+```
+
+**What's safe to send directly:** essentially everything sync (`server_*`, `bridge_list`, `hd_status`, `hd_build_status`, `desktop_list_windows`, `desktop_screenshot_*`, `kicad_*`, `fusion_*`, `pup_screenshot`, `notify_user`, ...) plus async-dispatching verbs that return a job id in <500 ms (`bridge_install`, `hd_build`, `desktop_install_kicad`, ...).
+
+**What requires the CLI fallback:** verbs returning a structured `errorCode:"cli_required"` from this endpoint — currently `pull_file`, `send_files`, `shell_execute`. These use binary streaming or multi-minute approval polling that doesn't fit a single synchronous HTTP request. `GET /status` returns the full list at runtime so callers can branch defensively.
+
+Full integration guide (loopback trust model, recipes for Hydrogen startup/shutdown, retry/backoff patterns, port-discovery code in Rust + TypeScript) lives in [`skills/DIRECT_API.md`](DIRECT_API.md) in this repo, and as a wiki asset attached to `apps/adom-bridge`.
+
+#### Embedded mode — ab bundled inside Hydrogen (v1.8.42+)
+
+When Hydrogen bundles ab, ab enters "embedded mode" at boot. Hydrogen owns the system-tray icon (ab's is suppressed), Hydrogen owns the Adom Cloud login (Hydrogen's session token is handed to ab via Phase 4's existing channels), Hydrogen owns auto-updates (ab's wiki-poll is disabled — Hydrogen bundles a fresh ab on every Hydrogen release), and Hydrogen spawns ab hidden (its tray "Open Adom Bridge" surfaces the window on demand). Standalone ab users see zero change — none of the signals fire.
+
+**Detection** — three-signal cascade (any one triggers embedded mode):
+
+1. `--embedded` CLI flag (what Hydrogen passes on every spawn)
+2. `ADOM_EMBEDDED=1` env var (backup channel)
+3. `%LOCALAPPDATA%\Adom Bridge\embedded.json` marker file (survives ab restarts; written by Hydrogen's installer; deleted by Hydrogen's uninstaller)
+
+**CLI flags Hydrogen passes when spawning ab**:
+
+```bash
+adom-bridge.exe --embedded --start-hidden \
+  --relay-url ws://127.0.0.1:8765 --relay-name hydrogen-desktop \
+  --session-token <hd's-stored-token>
+```
+
+- `--embedded` → enter embedded mode (also writes the marker)
+- `--start-hidden` → boot with main window invisible. **v1.8.119+: honored in embedded mode** (Hydrogen owns the surface; ab stays in the tray and opens via `desktop_window_show`). v1.8.102–118 had a bug where embedded mode force-showed the window even with `--start-hidden`; that's fixed. The machine owner can still flip ab's "Always show the window at launch" Settings checkbox (config `always_show_window_on_launch`, default OFF) to override and always show — a personal-dev-box preference, not the product default.
+- `--shell-approval <prompt|1h|24h|permanent>` → Hydrogen's passthrough of its user's shell-approval choice (v1.8.116+, session-only)
+- `--relay-url <url>` → upsert this relay via existing `server_add` dedup; default name `hydrogen-desktop`
+- `--relay-name <name>` → override the default name
+- `--session-token <tok>` → already covered by Phase 4 handoff (env / CLI arg / file)
+
+**Docker introspection** — `adom-bridge desktop_embedded_status` returns `{embedded, owner, source, enteredVia, pendingRelayUrl, pendingRelayName, startHidden, markerPath, markerExists}` so cloud-side callers can branch on whether ab is standalone or Hydrogen-managed. **v1.8.73+:** `enteredVia` reports `"launch-flag"` (Hydrogen spawned ab as a child via `--embedded`) or `"runtime-adopt"` (ab was running standalone; Hydrogen adopted it at runtime) — see "Runtime adopt + release" below.
+
+**New verbs Hydrogen uses to drive ab** (all also usable standalone):
+
+| Verb | Purpose |
+|---|---|
+| `desktop_window_show` | Bring ab's main window to foreground |
+| `desktop_window_hide` | Hide ab's main window (app keeps running) |
+| `desktop_connect_all` | Spawn ws_loop for every enabled server |
+| `desktop_disconnect_all` | Drop every live WS connection (entries stay in config) |
+| `desktop_shutdown` | Explicit ab termination (stop bridges, then exit) |
+| `desktop_embedded_status` | Introspect current embedded state (incl. `enteredVia`) |
+| `desktop_embedded_enter` | **v1.8.73+** runtime adopt: standalone → embedded as `runtime-adopt` |
+| `desktop_embedded_release` | **v1.8.73+** revert to standalone. **v1.8.77+: always reverts, never exits ab** (regardless of `entered_via`) — use `desktop_shutdown` for explicit exit |
+| `desktop_logout` | Clear ab's `~/.adom/session.json` (Hydrogen's sign-out propagation) |
+
+#### Runtime adopt + release (v1.8.73+) — the LaunchFlag-vs-RuntimeAdopt distinction
+
+Hydrogen has two ways to put ab into embedded mode:
+
+1. **Spawn ab with `--embedded`** (LaunchFlag) — Hydrogen launches a fresh ab process as its child. ab enters embedded with `entered_via=launch-flag`. When Hydrogen subsequently dies ungracefully (without calling `/embedded/release` or `desktop_shutdown` first), ab's 60s `embedded_monitor` tick notices Hydrogen's control port is dead and **exits ab** (the "no hanging chad" rule — no tray-less orphan).
+2. **Adopt at runtime via `POST /embedded/enter`** (RuntimeAdopt) — ab was already running standalone; Hydrogen calls the direct-API endpoint to flip ab into embedded mode without a respawn. ab enters embedded with `entered_via=runtime-adopt`, preserving its open state, current PID, all in-flight connections. When Hydrogen subsequently dies ungracefully, ab's monitor **reverts ab to standalone** — tray restored, footer pill hidden, marker deleted. ab process stays alive.
+
+The rule is simple: **whoever started ab owns ab's death**. If ab started itself (standalone → runtime adopt), Hydrogen's death doesn't take ab down with it.
+
+**Two new direct-API endpoints** (v1.8.73+, sugar over `POST /command`):
+
+```bash
+# Adopt — runs the same handler as desktop_embedded_enter:
+curl -s -X POST http://127.0.0.1:47200/embedded/enter
+
+# Release — runs the same handler as desktop_embedded_release.
+# v1.8.77+: ALWAYS reverts to standalone. ab never exits via this call.
+curl -s -X POST http://127.0.0.1:47200/embedded/release
+```
+
+**Probe target (v1.8.75+):** the 60s `embedded_monitor` checks Hydrogen's *control port* (default `47084`, discovered from `%APPDATA%\hydrogen-desktop\ports.json` key `control`), not Hydrogen's legacy `:9001` webview-eval port. Same discovery `hd_api` uses. Pre-v1.8.75 this was hardcoded to `:9001` — Hydrogen doesn't bind that port anymore, so the probe always reported Hydrogen dead and every embedded ab reverted/exited within 60s of Hydrogen starting.
+
+**Live frontend update (v1.8.76+):** the "Embedded · Hydrogen" footer pill responds to Tauri `mode-changed` events emitted on every transition. So if ab's window is open when Hydrogen adopts it (or Hydrogen releases it), the pill flips immediately — no page reload, no manual refresh.
+
+**Stale-marker safety (v1.8.74+):** if the marker file says `entered_via=launch-flag` AND Hydrogen's control port isn't responding at boot, ab deletes the marker BEFORE exiting. Without the delete, every subsequent manual launch (no `--embedded` flag) would hit the same exit branch and ab would be unlaunchable until the user manually rm'd the marker. The delete-before-exit makes the next launch start standalone normally.
+
+**Shell auto-approve is a user preference** (v1.8.116+ — replaces the v1.8.44 embedded-permanent default). The safe default everywhere is per-command approval. Resolution order at ab boot:
+
+1. `--shell-approval <prompt|1h|24h|permanent>` launch flag — Hydrogen's passthrough of its user's choice when spawning ab embedded. **Session-only**: never persisted by ab.
+2. The durable Settings checkbox ("Auto-approve shell commands permanently", config field `shell_auto_approve_permanent`, default OFF). Also set/cleared via `shell_auto_approve '{"permanent": true|false}'`.
+3. A restored timed grant from a previous session (+1h/+24h buttons, `duration_secs` calls).
+4. Otherwise: prompt per command.
+
+In embedded mode **Hydrogen owns the preference** (Hydrogen is the parent, ab the child): ab's Settings checkbox goes read-only with "Managed by Hydrogen", and the footer shows "**Permanent** *(managed by Hydrogen)*" when armed. Hydrogen changes it at runtime with the same verb:
+
+```bash
+# revoke everything (timed + permanent + the saved checkbox):
+adom-bridge shell_auto_approve '{"duration_secs": 0}'
+
+# set the durable preference (equivalent to ticking the Settings checkbox):
+adom-bridge shell_auto_approve '{"permanent": true}'
+```
+
+Migration note: pre-1.8.116 embedded boots persisted a permanent grant that leaked into standalone sessions. On first v1.8.116 boot, a permanent-class grant on disk WITHOUT the config preference is cleared — re-opt-in via the checkbox or the verb if you actually wanted it.
+
+**⚠ v1.9.90 — a cloud/relay AI CANNOT grant shell approval itself.** The `shell_auto_approve` examples above are Hydrogen's (a trusted LOCAL caller) or the human's own. From a **relay** connection (the cloud AI), a GRANT (`shell_auto_approve {"permanent":true}` / `{"duration_secs":N>0}`) is REFUSED with `errorCode:"human_only"` and instead POPS the human approval prompt in Adom Bridge. **The AI's path: call `request_shell_approval` (or just let the gate/refusal auto-surface the prompt) → ask the user to click Approve 1 hr / 24 hr / Bypass Permissions → RETRY your original verb.** Only a human clicking in ab (or Hydrogen proxying its own user) grants. A REVOKE (`duration_secs:0`) is allowed for the AI.
+
+#### Bridge ports are dynamic — you never need to know one (v1.8.31+)
+
+KiCad, Fusion, Browser/Puppeteer, and all third-party bridges now bind OS-assigned ephemeral ports (not the legacy 8772/8773/8851 you may remember). The runtime port changes every spawn. **Callers never need to know it.**
+
+- The CLI verb namespace (`kicad_*`, `fusion_*`, `pup_*`, plus any third-party `<bridge>_*`) is the contract. Always go through that.
+- adom-bridge's direct API forwards to whatever port each bridge is on at the moment of the call.
+- `bridge_list` reports `spawn.runtimePort` per bridge for debugging — do NOT hardcode it anywhere.
+- Why this changed: Hydrogen's bridges also wanted 8772/8773/8851; we used to collide silently. Dynamic ports = clean coexistence.
+
+### Managing bridges (the AI fully controls bridges on its own)
+
+Bridges are ab's plugins (kicad, puppeteer, fusion360 ship bundled; others install from the wiki). You — the AI — can see, update, install, remove, pause, and resume them entirely through verbs. No human step is required.
+
+| Verb | What it does |
+|---|---|
+| `bridge_list` | Every installed bridge: `name`, `displayName`, `version` (what ab runs now), `source` (bundled / cache / third_party), `paused`, spawn kind, verbPrefixes. Start here. |
+| `bridge_check_updates` | **READ-ONLY.** Per bridge: `current` vs `latest` (wiki) + `updateAvailable`. Downloads nothing. The "what's behind?" probe. |
+| `refresh_bridges` | Apply updates. No args = sync ALL bridges from the wiki. `{"name":"kicad"}` = update just one. |
+| `bridge_install` | Install a new third-party bridge from a wiki manifest URL (`{"manifestUrl":"…/<bridge>-bridge-manifest.json"}`). On `success:true` the **capsule appears in the ab GUI immediately** (no verb call needed; it's gray/idle until first use, then green). On `success:false` **nothing is registered and no capsule appears** — read `error` (a `read zip body`/`builder error` means the manifest's zip URL couldn't be fetched). Don't treat a parsed manifest as a completed install; confirm with `bridge_list`. The manifest `url` may be relative (resolved against the manifest's dir, v1.8.169+). |
+| `bridge_uninstall` | Remove a bridge (`{"name":"…"}`). Bundled ones revert to the bundled copy; third-party ones are fully removed. |
+| `bridge_pause` / `bridge_resume` | Flip a routing flag so a bridge's verbs fail-fast with `bridge_paused` (or resume). Does NOT kill the process. |
+| `bridge_dev_mode` | **The DEV PIN** (`{"name":"kicad","on":true}`): freeze that ONE bridge against ALL automatic updates (the 4h sweep, on-launch sync, on-use auto-update, refresh_bridges) so a developer can modify its installed cache without ab pulling the release over their work. `on:false` releases it. `bridge_list` shows `devPinned:true` and the ab GUI card shows an amber "dev pin" badge with a one-click Unpin. **Etiquette: if a bridge shows `devPinned:true`, a human is mid-development on it - never unpin or force-update it to "get the latest" without asking them.** If YOU are about to edit a bridge's installed files, pin it FIRST. |
+
+**Naming convention for published bridges (3rd-party authors, read this):** when you publish a bridge to the Adom wiki, its **page title / catalog descriptive name MUST start with `Adom Bridge - `** (spaced hyphen) — e.g. `Adom Bridge - Altium Bridge`, matching the bundled bridges (`Adom Bridge - Puppeteer Bridge`, `Adom Bridge - KiCad Bridge`). This keeps every ab bridge grouped with consistent names in app-index pages instead of scattering as bare slugs. It applies to the **wiki/catalog title only** — NOT `bridge.json` `displayName` (the in-app chip label, which stays tool-descriptive like `Altium Designer`) or `name` (the lowercase slug). Full authoring walkthrough: the `adom-bridge-bridge-sdk` skill (the `adom-bridge-sdk` wiki page) + its fill-in-the-blanks templates.
+
+**Typical "am I on the latest bridges?" flow:**
+```bash
+adom-bridge bridge_check_updates            # read-only: see current vs wiki per bridge
+# → {bridges:[{name,current,latest,updateAvailable,source,wikiReachable}], updatesAvailable:N}
+adom-bridge refresh_bridges                  # update ALL that are behind
+adom-bridge refresh_bridges '{"name":"kicad"}'   # or just one
+```
+
+**Version semantics (so the numbers make sense):**
+- `current` = what ab actually runs = the newer of the writable cache and the bundled copy (version-aware, numeric semver — `1.0.10 > 1.0.9`).
+- A bundled bridge that ships AHEAD of the wiki shows `updateAvailable:false` — ab correctly keeps the newer bundled copy. **puppeteer is bundled-only** (its node_modules deps exceed the wiki file limit), so it never shows a wiki update; it updates with the ab installer.
+- After an `updated` action, the bridge SERVER PROCESS still holds the old code in memory until it respawns. `is_bridge_running` is version-aware (v1.8.142+) and forces a respawn on the next verb call, so you normally don't need to kill anything — but if you want it instant: `taskkill /f /im python.exe` (kicad/fusion) or `node.exe` (puppeteer).
+
+**Auto-update cadence:** a running ab also auto-syncs bridges on launch + every 4 hours. `bridge_check_updates` / `refresh_bridges` (or the GUI's **"Check for updates"** button next to "+ Bridge") are the on-demand "I just published, pick it up now" path.
+
+#### Bridge lifecycle — one instance, stable port (v1.8.153+)
+
+A dynamic bridge gets **one stable port** that ab reuses across every spawn and across ab restarts (persisted in `~/.adom/bridge-ports.json`). A long-lived external client (e.g. a browser extension that dials the bridge) keeps reaching the same port — no chasing a fresh ephemeral port each cycle, no "the client is on bridge A but ab routes to bridge B" split. ab enforces a **single instance**: it tracks every spawned bridge PID, reaps a stale/wedged one before respawning on the same port, and `bridge_stop_all` reaps orphans too.
+
+`spawn.persistent` (in `bridge.json`) is now surfaced in `bridge_list` (`spawn.persistent`) and means: **ab auto-respawns this bridge on death**, on its stable port (a supervisor runs each ~15 s). So "kill the bridge to load new code" → ab brings it right back at the same port the client keeps dialing. `bridge_install` / `refresh_bridges` also no longer fail with the cache-dir lock (ab reaps the process holding the dir as its cwd, then swaps; in-place merge fallback if a handle lingers).
+
+**v1.8.186/187 — first-class bridges (panel + remote management + optional manifest fields).** The ab window has a full-height **Bridges sidebar** that shows each bridge as a mini-app (hero image, LED, rich tooltip); clicking one opens a wide pop-out with a **live console** (its `~/.adom/bridge-logs/<name>.log` + the per-bridge command history), a **ports/process debug view** (live PIDs — `>1` flags a runaway), persistent-vs-one-off + codebase-language badges, and all management actions (install/uninstall/**kill**/restart/pause/resume + "filter activity log to this bridge" + "copy contribution prompt"). The same management is available **remotely** to cloud/WSL2 threads via verbs: `bridge_info`/`bridge_detail` (rich aggregate), `bridge_log_read {name, sinceOffset?}` (**cursor-streaming remote tail -f**), `bridge_kill` (wipe one bridge's processes). As of v1.8.186 **all** bridges write their per-bridge log (bundled kicad/fusion360/puppeteer included, not just dynamic ones). New **optional** `bridge.json` fields (all back-compat, surfaced in the panel): `hero` (a relative filename on your wiki page, or a full URL — your app-icon; absent → a monogram tile), `languages` (override the auto-scan, e.g. `["Python"]`), `releasedAt` (ISO date; absent → bridge.json mtime).
+
+**v1.8.156 — strays + self-documenting hints.** ab now tracks every bridge PID it spawns (persisted across ab restarts) and **reaps all stray instances** before respawning — so you don't end up with 4 copies of one bridge fighting over the routing. `bridge_list` surfaces `spawn.instanceCount` per dynamic bridge (normally 0 or 1; **>1 = strays piled up** — visible at a glance). If a bridge verb fails to reach a healthy bridge, the error `_hint` tells you to retry / check `instanceCount` / `process_list`; and a verb response right after a (re)spawn carries an `_ad_note` saying the external host reconnects within a few seconds — **retry** instead of treating a transient "not connected" as terminal. For verb discovery from a bridge, `GET <ADOM_DIRECT_API_URL>/commands` lists every reachable verb (see [`skills/DIRECT_API.md`](DIRECT_API.md)).
+
+#### Bridge status chip — self-reported LED + tooltip (v1.8.152+)
+
+Each bridge has a status dot in the ab GUI sidebar. **ab is a pure renderer of bridge health** — a live bridge decides its own LED color and hover text; ab just paints what the bridge reports. This replaced the old scheme where ab inferred the LED from whether it was holding a spawn handle, which left fire-and-forget (dynamic/installed) bridges stuck RED even while healthy and routing.
+
+**The contract (all three fields OPTIONAL).** On the endpoint ab already polls — your `bridge.json` `healthEndpoint` (default `/health`; the sample bridges use `/status`) — return a 2xx JSON body that MAY include:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `led` | `"green"` \| `"yellow"` \| `"red"` | The dot color. Green = healthy; yellow = degraded/warning; red = the bridge itself knows it's broken (e.g. lost its upstream). |
+| `summary` | string | Short label shown next to the dot. Keep it tiny (≤ ~24 chars) — e.g. `"2 windows"`, `"ext disconnected"`. |
+| `tooltip` | string | Full hover text. Newlines allowed; no hard length limit (keep it readable). |
+
+**Rules ab enforces:**
+- Endpoint returns 2xx **with** `led`/`summary`/`tooltip` → rendered **verbatim**, no parsing or logic.
+- Endpoint returns 2xx **without** them → ab defaults to **green** (you're reachable) + a generic tooltip. Existing bridges work unchanged — this is opt-in.
+- Endpoint **unreachable** → ab owns this ONE state: a **gray/offline** dot + ab's own tooltip ("Not running" / "Bridge not reachable"). A dead bridge can't self-report, so ab never lets a bridge claim "offline" — it detects it.
+
+**Cadence:** ab re-polls every ~15 s, and a dynamic bridge flips green the instant it spawns. So a bridge that surfaces live counters (open windows, queue depth, ext-connection state) in `summary`/`tooltip` updates in the GUI within a tick.
+
+Reference implementations: [`scripts/sample-bridges/hello-python/server.py`](../scripts/sample-bridges/hello-python/server.py) and [`hello-rust/src/main.rs`](../scripts/sample-bridges/hello-rust/src/main.rs) both self-report `led`/`summary`/`tooltip` on `/status` — fork either.
+
+### File Transfer
+
+- `send_files` -- Send files from the Docker container to the desktop. Files are base64-encoded in transit.
+  - `filePaths`: array of absolute paths on the server
+  - `targetApp`: "kicad", "fusion360", or "general"
+  - `dest`: **absolute** Windows path (under a safe root) to land the files exactly where you want (v1.8.148+). Prefer this when you know the target dir.
+  - `destinationFolder`: **relative subfolder only** (e.g. `"kicad/symbols"`, `"fusion"`). The desktop app controls the base directory. **Absolute paths are rejected.** With neither `dest` nor `destinationFolder`, files land in the laptop's **Downloads** folder.
+  - Returns `destinationPaths[]` with the absolute path of every saved file, plus (v1.8.168) `savedToDir` (the folder) and a rich `_hint`. **The files land on the LAPTOP (Windows host), not in your container** — verify with `list_dir`, pull one back with `pull_file`.
+  - **`send_files` only COPIES bytes — it does NOT install or register a bridge.** Dropping bridge files with `send_files` will NOT make a capsule appear or verbs route. To add a bridge use `bridge_install '{"manifestUrl":"…/<bridge>-bridge-manifest.json"}'`, then confirm with `bridge_list`.
+
+- `pull_file` -- Pull files from the desktop to the container.
+  - `filePaths`: array of absolute Windows paths on the desktop
+  - `saveTo`: directory on the container to save files (default: `/tmp`)
+  - **Streaming since v1.4.3.** Each file is transferred as 1 MiB binary WS frames straight to disk on the Docker side, with incremental SHA256 verification. The legacy 30s base64-JSON path is gone — large files (50 MB+ datasheets, 75 MB reference manuals) no longer time out. Per-file timeout is 600s.
+  - Returns `files: [{name, path, size, sha256, chunks}]`. Use `sha256` to verify the transfer (the desktop side computes it during streaming and the container side verifies on completion; mismatch deletes the partial file and reports failure). `chunks` is the count of 1 MiB binary frames received.
+  - When at least one but not all files succeed: `success` is `true`, `errors[]` lists the failures alongside `files[]`. When ALL fail: `success` is `false`.
+
+### Desktop Notifications
+
+- `notify_user` -- Send a native Windows toast (own AUMID + Adom logo). v1.9.33: rich types — progress bar, sticky reminder, action buttons that **bring ab to the foreground** on click + round-trip via `notify_response`.
+  - `title`, `body`, `level` (info/success/warning/error/emergency), `actions` (label buttons) — plus `scenario` ("reminder"=sticky), `durationLong`, `buttons` (`[{label, arguments?}]`), `progress` (`{title, value 0..1, status, valueOverride}`), `inputs`, `id` (correlation id for the round-trip).
+  - Full guide + copy-paste examples per type: the **adom-bridge-notify** skill ([`skills/NOTIFY.md`](NOTIFY.md)).
+- `notify_response` -- Poll which toast button the user clicked, by correlation `id`. `{pending:true}` until they click; `{pending:false, action}` once they do (consumed on read).
+
+### KiCad (`kicad_*`) — bridge-owned; light pointer
+
+The KiCad bridge is **cloud-owned** and ships its OWN full skill (wiki pkg `adom/kicad-bridge`). This page keeps only the pointer: run `adom-bridge sync_skills` after connecting and the full KiCad guide (project workflows, three-tier `kicad_open_*` routing, DRC recipes, library install) lands in `~/.claude/skills/`.
+
+Most-used verbs to get moving:
+
+```bash
+adom-bridge kicad_open_board '{"path": "C:/projects/board/board.kicad_pcb"}'
+adom-bridge kicad_screenshot_all '{}'          # every KiCad window incl. error dialogs, as an array
+adom-bridge kicad_run_drc '{}'
+adom-bridge kicad_window_info '{}'
+adom-bridge kicad_open_symbol_editor '{"library": "Device"}'
+```
+
+If KiCad is not installed, the bridge knows how to install it for the user — offer, never point them at a download page. Full details: the bridge's own skill.
+
+### Fusion 360 (`fusion_*`) — bridge-owned; light pointer
+
+The Fusion 360 bridge is **cloud-owned** and ships its OWN full skill (wiki pkg `adom/fusion-bridge`). Run `adom-bridge sync_skills` and the full guide (cloud files, import/export, add-in troubleshooting, APS search) lands in `~/.claude/skills/`.
+
+Most-used verbs:
+
+```bash
+adom-bridge fusion_start '{}'                       # launches Fusion; slow on cold start (minutes)
+adom-bridge fusion_get_app_state '{}'               # the status/poll verb
+adom-bridge fusion_addin_status '{}'
+adom-bridge fusion_dismiss_blocking_dialogs '{}'
+adom-bridge fusion_send_key '{"key": "Escape"}'
+```
+
+Fusion launches take 2-4 minutes cold; respect `timeoutSeconds` + `statusVerb` on responses instead of re-issuing. Full details: the bridge's own skill.
+
+### Launching apps (generic)
+
+Two generic CLI commands exist for launching any Windows executable safely — they verify the target exists BEFORE handing it to the OS, so you never trigger a "Windows cannot find" GUI dialog:
+
+- `adom-bridge find_exe '{"name":"..."}'` -- Resolve an exe by absolute path, glob (e.g. `C:/.../webdeploy/production/*/Fusion360.exe` returns newest), bare name (searches PATH + Start Menu `.lnk` targets). Returns `{path, source}`. Does NOT launch.
+- `adom-bridge launch '{"path":"...", "args":[...], "cwd":"...", "detached":true}'` -- Same resolution rules as `find_exe`, then spawns. Fails in terminal (exit 1) with a clear error if the path doesn't exist. **Always prefer this over raw `start`.**
+
+For Fusion specifically, use `fusion_start` — it wraps `launch` plus the full startup-picker / add-in-readiness dance.
+- `fusion_import_step` -- Import a STEP/STL/IGES file into Fusion 360
+- `fusion_open_lbr` -- Open an EAGLE .lbr library file
+- `fusion_open_electronics` -- Check if the Electronics workspace is active
+- `fusion_electron_run` -- Execute any EAGLE command via Electron.run. Returns rich state: `activeWorkspace`, `activeDocument`, `commandType`, `_hint`, and `fusionOperations` (diff of Fusion's internal operation log showing what actually fired). **Avoid blocking commands** — see list below. **Full EAGLE command reference:** [`skills/eagle-commands.md`](./eagle-commands.md) — popular/safe commands split from blocking/modal ones, with layer reference and chaining syntax.
+- `fusion_execute_text_command` -- Low-level app.executeTextCommand() access. Returns the command result plus workspace context.
+- `fusion_board_info` -- Get structured board data from the open PCB layout. Returns: component placements (name, package, x, y, rotation), net names, copper traces, layer setup, board thickness, DRC violations. Much richer than a screenshot — gives exact coordinates and connectivity. Requires a .brd board open in PCB Editor.
+
+#### `fusion_electron_run` — EAGLE Command Execution
+
+Executes EAGLE commands inside Fusion 360's Electronics workspace. Works in **Schematic Editor**, **PCB Editor (Board Layout)**, and **Electronics Library** contexts.
+
+**How it works:** Sends the command string via Fusion's `Electron.run` text command. EAGLE's `Electron.run` is fire-and-forget — it never returns output or throws on invalid commands. To compensate, the handler snapshots Fusion's internal operation log (`Diagnostics.RecentOperations`) before and after execution, returning a diff showing what actually fired.
+
+**Usage:**
+```bash
+# Basic command
+adom-bridge fusion_electron_run '{"command": "WINDOW FIT"}'
+
+# Multiple commands in sequence (use semicolons)
+adom-bridge fusion_electron_run '{"command": "DISPLAY NONE; DISPLAY 1 16 17 18 20 21"}'
+
+# Navigate in library editor
+adom-bridge fusion_electron_run '{"command": "EDIT SOIC8.pac"}'
+adom-bridge fusion_electron_run '{"command": "EDIT RESISTOR.sym"}'
+adom-bridge fusion_electron_run '{"command": "EDIT MYDEVICE.dev"}'
+```
+
+**Response fields:**
+- `activeWorkspace` — Current workspace (Schematic Editor, PCB Editor, Electronics Library)
+- `activeDocument` — Name of the open document
+- `commandType` — Detected type: `view_control`, `layer_control`, `edit`, `design_rule`, etc.
+- `editorType` — For EDIT commands: `package`, `symbol`, `device`
+- `fusionOperations` — Array of Fusion operations that fired (diff of internal log)
+- `hint` — Human-readable description of what happened
+- `rawResult` — Raw return from Electron.run (usually empty)
+
+**EAGLE Command Reference — Safe for automation:**
+
+| Command | Context | Description |
+|---------|---------|-------------|
+| **View / Navigation** | | |
+| `WINDOW FIT` | Any | Zoom to fit all content |
+| `WINDOW (x1 y1 x2 y2)` | Any | Zoom to specific area (coordinates in current units) |
+| `DISPLAY ALL` | Any | Show all layers |
+| `DISPLAY NONE` | Any | Hide all layers |
+| `DISPLAY 1 16 17 18 20 21` | Board | Show specific layers by number |
+| **Grid** | | |
+| `GRID MM 0.1` | Any | Set grid to 0.1mm |
+| `GRID MIL 25` | Any | Set grid to 25mil |
+| `GRID INCH 0.05` | Any | Set grid to 0.05 inch |
+| **Board Layout** | | |
+| `RATSNEST` | Board | Recalculate airwires (unrouted connections) |
+| `RIPUP` | Board | Remove all routed traces |
+| `RIPUP *` | Board | Remove all traces (same as RIPUP with no selection) |
+| `ROUTE` | Board | Start auto-router |
+| `DRC` | Board | Run design rule check |
+| `BOARD` | Schematic | Switch to paired board layout |
+| `SCHEMATIC` | Board | Switch to paired schematic |
+| **Schematic** | | |
+| `VALUE value` | Schematic | Set component value |
+| `NAME name` | Any | Rename selected element |
+| `SMASH` | Any | Detach name/value labels from components |
+| **Library Editor** | | |
+| `EDIT name.pac` | Library | Open a package (footprint) for editing |
+| `EDIT name.sym` | Library | Open a symbol for editing |
+| `EDIT name.dev` | Library | Open a deviceset for editing |
+| `EXPORT SCRIPT 'path.scr'` | Library | Export entire library as EAGLE script |
+| **Scripting / Settings** | | |
+| `SET CONFIRM YES` | Any | Suppress confirmation dialogs |
+| `SET CONFIRM OFF` | Any | Re-enable confirmation dialogs |
+| `SCRIPT 'path.scr'` | Any | Run batch commands from a .scr script file |
+
+**EAGLE Layer Numbers (commonly used):**
+
+| Layer | Name | What it shows |
+|-------|------|--------------|
+| 1 | Top | Top copper |
+| 16 | Bottom | Bottom copper |
+| 17 | Pads | Through-hole pads |
+| 18 | Vias | Via holes |
+| 19 | Unrouted | Airwires (ratsnest) |
+| 20 | Dimension | Board outline (required for 3D) |
+| 21 | tPlace | Top silkscreen |
+| 22 | bPlace | Bottom silkscreen |
+| 25 | tNames | Top component names |
+| 27 | tValues | Top component values |
+| 29 | tStop | Top solder mask |
+| 31 | tCream | Top stencil/paste |
+| 51 | tDocu | Top documentation |
+
+**Blocking commands — AVOID from automation:**
+
+| Command | Why it blocks |
+|---------|---------------|
+| `WRITE` | Opens Save As dialog — use `fusion_save_lbr` or `fusion_close_document` instead |
+| `ADD` | Opens component picker dialog |
+| `SHOW name` | Opens interactive highlight mode |
+| `SET` (no params) | Opens settings dialog |
+| `GRID` (no params) | Opens grid settings dialog |
+| `EDIT new.sym` | Opens "Create new?" confirmation if symbol doesn't exist |
+| `CHANGE` | Opens interactive change mode |
+| `MOVE` | Opens interactive move mode |
+
+**Tips:**
+- Always run `WINDOW FIT` after opening a file or switching views
+- Use `DISPLAY NONE` then `DISPLAY <layers>` to show only specific layers
+- Combine commands with `;` — e.g., `SET CONFIRM YES; RIPUP *; RATSNEST`
+- For board screenshots: `DISPLAY NONE; DISPLAY 1 16 17 18 20 21; WINDOW FIT`
+- Use `fusion_board_info` instead of EAGLE commands when you need structured data
+- `fusion_export_lbr` -- Export the open Electronics library as an EAGLE .scr script (note: does NOT include 3D package references — those are cloud-linked only)
+- `fusion_save_lbr` -- Save the open Electronics library as a .flbr file
+
+#### EAGLE Libraries with 3D Packages
+
+Fusion 360's .lbr format supports `package3d` elements that link footprints to 3D models. Key facts:
+
+- **3D models are cloud-hosted** — each `package3d` has a `wip_urn` (e.g., `urn:adsk.wipprod:fs.file:vf.xxxxx`) pointing to a Fusion cloud document. You cannot embed STEP files directly in .lbr XML.
+- **Creating 3D packages requires the Fusion UI** — use `Package3DCreateCmd` in Electronics Library Editor, which opens a new Design workspace where you model/import the 3D shape, then save to link it.
+- **`EXPORT SCRIPT` strips 3D references** — the .scr export only contains 2D data (symbols, footprints, devicesets). To preserve 3D links, keep the .lbr XML format.
+- **Fusion's built-in examples** have 3D packages — 34 of 37 libraries in the EAGLE examples directory (e.g., `Connector_USB.lbr`, `Resistor.lbr`, `Capacitor.lbr`) include `package3d` references.
+- **Example libraries location**: `%LOCALAPPDATA%/Autodesk/webdeploy/production/<hash>/Applications/Electron/LibEagle/examples/libraries/examples/`
+
+To open a built-in example library for reference:
+```bash
+# Find the examples directory first
+adom-bridge fusion_execute_text_command '{"command": "Python.RunScript C:/tmp/find_eagle_libs.py"}'
+# Then open one
+adom-bridge fusion_open_lbr '{"filePath": "<path>/Connector_USB.lbr"}'
+```
+- `fusion_open_schematic` -- Open a .sch schematic in Fusion's Schematic Editor. Args: `filePath`.
+- `fusion_open_board` -- Open a .brd board layout in Fusion's Board Layout editor. Args: `filePath`.
+- `fusion_show_3d_board` -- Switch to 3D PCB board view (must have a .brd open). Board MUST have an outline on layer 20 (Dimension) or 3D generation fails. Auto-zooms to fit after switching.
+- `fusion_show_2d_board` -- Switch back to 2D board layout from 3D PCB view. EAGLE commands via `fusion_electron_run` only work in 2D.
+- `fusion_close_document` -- Close a document without save dialog. Args: `name` (optional, defaults to active doc), `save` (optional, default false). Essential for automation — avoids modal save dialog that blocks Fusion.
+- `fusion_document_info` -- List ALL open documents/tabs with name, type, and active status, plus detailed cloud info for the active document. Returns `openDocuments` array (every tab) and active doc details (cloud project, folder, file ID, version, save status). Lightweight — uses only in-memory data, no cloud API calls. Use this instead of `fusion_walk_cloud_tree` when you just need to know what's open.
+- `fusion_activate_document` -- Switch to a specific open document tab. Args: `name` (substring match, case-insensitive), `documentType` ("Electronics", "PCB", "FusionDesign", "Drawing"). Essential for automation — switch between schematic, board, and library tabs without user interaction. If no match found, returns the list of open documents so you can refine.
+- `fusion_close` -- Close Fusion 360. **Always call this when done with Fusion 360 commands to clean up.**
+- `fusion_dismiss_recovery` -- Dismiss recovery document dialogs (both "Recovered Documents" list and "Open recovery document instead?" prompts). Also relocates recovery files to `~/.adom/recovery/fusion/` for safekeeping.
+- `fusion_relocate_recovery` -- Proactively move Fusion crash recovery files to `~/.adom/recovery/fusion/<timestamp>/` without dismissing any dialogs. Call this **before** launching Fusion to prevent recovery dialogs from appearing. Files are preserved (not deleted) so the user can manually restore them if needed.
+- `fusion_close_all_documents` -- Close all open documents. Args: `saveChanges` (default: false). Use before force-killing Fusion to prevent recovery files.
+
+#### Fusion 360 UI Interaction
+
+Commands for interacting with Fusion 360's UI — detecting dialogs, taking screenshots, clicking, and sending keyboard input. Essential for handling blocking dialogs and automating CEF-based UI elements.
+
+- `fusion_window_info` -- Returns the Fusion main window HWND, title, rect, and a list of all Qt dialog windows (recovery dialogs, wizards, file pickers). Essential for detecting blocking dialogs before/after operations.
+  - Example: `adom-bridge fusion_window_info`
+  - Returns: `{hwnd, title, rect, dialogs: [{hwnd, title, className, rect}]}`
+
+- `fusion_screenshot_fusion` -- Captures the Fusion main window or a specific dialog by HWND. Uses PrintWindow (works without bringing to foreground). Saves WebP to `C:/tmp/adom-bridge-screenshots/` (falls back to PNG if WebP unavailable). Downscaled to ≤1568px — use relative coords (0.0-1.0) for clicking, they're scale-independent. DPI-aware.
+  - Args: `hwnd` (optional — dialog HWND to screenshot instead of main window)
+  - Example: `adom-bridge fusion_screenshot_fusion` (main window)
+  - Example: `adom-bridge fusion_screenshot_fusion '{"hwnd": 12345}'` (specific dialog)
+
+- `fusion_screenshot_all` -- Screenshots the main Fusion window and lists all dialog windows with their HWNDs. Use `fusion_screenshot_fusion {"hwnd": ...}` to capture each dialog.
+  - Example: `adom-bridge fusion_screenshot_all`
+
+- `fusion_click_fusion` -- Click at coordinates within the Fusion window or a specific dialog. x/y are relative (0.0-1.0) by default. Set `"relative": false` for pixel offsets. Uses SendInput for CEF dialog compatibility. **Prefer `fusion_send_key` for dialogs** — enter/escape/tab covers most cases.
+  - Args: `x` (required), `y` (required), `relative` (optional, default true), `hwnd` (optional — target a specific dialog HWND instead of main window)
+  - Example: `adom-bridge fusion_click_fusion '{"x": 0.5, "y": 0.7}'` (main window)
+  - Example: `adom-bridge fusion_click_fusion '{"hwnd": 12345, "x": 0.75, "y": 0.85}'` (dialog button)
+
+- `fusion_send_key` -- Send keyboard input to Fusion or a specific dialog via SendInput. **Preferred way to dismiss dialogs**: enter to confirm, escape to cancel, tab to cycle buttons. Use click only if tab order doesn't reach the right button.
+  - Args: `key` (required), `hwnd` (optional — target a specific dialog HWND)
+  - Example: `adom-bridge fusion_send_key '{"key": "escape"}'` (dismiss CEF dialog)
+  - Example: `adom-bridge fusion_send_key '{"key": "enter", "hwnd": 12345}'` (confirm dialog)
+
+#### Fusion 360 Workflow Guide
+
+##### Opening Electronics Projects
+1. Open the `.fprj` file: `adom-bridge fusion_open_cloud_file '{"projectName":"Main","fileName":"DRV8411A","fileExtension":"fprj","folderPath":"Molecules/XRP/DRV8411A"}'`
+2. Do NOT try to open `.fbrd` or `.fsch` directly — they fail or show a "Select Electronics Design File" dialog
+3. Enter the board editor: `adom-bridge fusion_show_2d_board`
+4. Enter the schematic editor: After step 3, use `adom-bridge fusion_electron_run '{"command":"EDIT .sch"}'`
+5. Switch back to board: `adom-bridge fusion_electron_run '{"command":"EDIT .brd"}'`
+
+##### Auto-Screenshot on Open Commands
+
+**Open commands automatically screenshot Fusion and return the images in the response.** The following commands include `postOpenScreenshot` in their `data` field:
+- `fusion_open_cloud_file`, `fusion_open_schematic`, `fusion_open_board`, `fusion_show_3d_board`, `fusion_show_2d_board`
+
+The response `data.postOpenScreenshot` contains:
+- `screenshots[]` — array of `{type, savedTo, sizeKB, title?, hwnd?}`. Type is `"main_window"` or `"dialog"`.
+- `message` — human-readable instruction to READ each screenshot and check for blocking dialogs
+- `dialogBlocking` — `true` if a modal dialog was detected
+
+**After receiving the response, you MUST:**
+1. **READ each screenshot file** using the Read tool to visually inspect what Fusion shows
+2. Look for blocking dialogs in the screenshots:
+   - "What to design?" wizard → dismiss with `fusion_send_key {"key": "escape"}`
+   - "PCB out of date" banner → click Update or X
+   - "Recovered Documents" → `fusion_dismiss_recovery`
+   - "Save changes?" → `fusion_send_key {"key": "escape"}`
+   - Any other modal → identify and dismiss
+3. **Screenshot again** after dismissing to confirm it's clear
+
+Screenshots are saved as WebP (lossless, ~20-40KB each, downscaled to ≤1568px) for token efficiency. Both the main Fusion window AND all Qt dialog windows are captured separately.
+
+**Why this matters**: Fusion shows Qt dialogs and CEF overlays that are invisible to the API. The `success: true` response from an open command does NOT mean the UI is ready — a dialog may be blocking all further operations. The API cannot detect these. Only a screenshot can.
+
+##### Detecting and Handling Blocking Dialogs
+- The auto-screenshot captures dialog windows separately (look for `type: "dialog"` entries in `postOpenScreenshot.screenshots[]`)
+- Common blocking dialogs: "What do you want to design?", "Recovered Documents", "Open recovery document instead?", "Select Electronics Design File"
+- Dismiss recovery dialogs: `adom-bridge fusion_dismiss_recovery`
+- Dismiss CEF dialogs (inside main window): `adom-bridge fusion_send_key '{"key": "escape"}'` or `fusion_click_fusion`
+- Dismiss "What do you want to design?" wizard: `adom-bridge fusion_send_key '{"key": "escape"}'`
+- For manual screenshot of specific dialogs: `adom-bridge desktop_screenshot_window '{"hwnd": <DIALOG_HWND>}'`
+
+##### Preventing Recovery Documents
+- Recovery files are at: `%LOCALAPPDATA%\Autodesk\Autodesk Fusion 360\<USER_ID>\CrashRecovery\`
+- Before force-killing Fusion, close all documents: `adom-bridge fusion_close_all_documents '{"saveChanges": false}'`
+- **Best practice**: Call `adom-bridge fusion_relocate_recovery` before launching Fusion. This moves recovery files to `~/.adom/recovery/fusion/<timestamp>/` — preserving them for the user while preventing modal dialogs.
+- The `fusion_start` command also auto-relocates recovery files before starting Fusion.
+- The `fusion_dismiss_recovery` command handles both "Recovered Documents" list and "Open recovery document instead?" prompts, and also relocates files.
+
+##### EAGLE Export Limitations
+- **Supported**: `EXPORT IMAGE`, `EXPORT NETLIST`, `EXPORT PARTLIST`
+- **NOT supported** (fail silently): `EXPORT DXF`, `EXPORT SVG`, `EXPORT DRILL`
+- Always verify export output: the updated `fusion_electron_run` now checks if the output file was created
+- Use `fusion_export_bom` and `fusion_export_cpl` for manufacturing data (these use the add-in's XML parser, not EAGLE export)
+- Use `fusion_export_gerbers` for Gerber files — produces a ZIP with all gerber layers (GTL, GBL, GTS, GBS, GTP, GBP, GTO, GBO, GKO, XLN). Auto-detects 2-layer vs 4-layer boards.
+
+##### 3D Model Exports
+- From the 3D view (activate the .f3d document): `fusion_export_step`, `fusion_export_stl`, `fusion_export_3mf`, `fusion_export_f3d`, `fusion_export_usdz`, `fusion_export_iges`, `fusion_export_sat`
+- Switch to 3D view: `fusion_show_3d_board` or activate the .f3d document
+- **STEP** — Industry-standard CAD interchange (SolidWorks, CATIA, Creo). Highest geometric fidelity.
+- **IGES** — Legacy CAD interchange. Use STEP for modern workflows.
+- **SAT** — ACIS solid model format. Used by SolidWorks, SpaceClaim.
+- **STL** — Mesh format for 3D printing and visualization. Options: refinement "low"/"medium"/"high".
+- **3MF** — Modern 3D printing with color/material support and multi-body.
+- **F3D** — Native Fusion 360 archive. Preserves parametric features, sketches, timeline, component refs. Best for archival.
+- **USDZ** — **Best for digital twins and GLB conversion.** Preserves full component hierarchy (Board, copper layers, soldermask, Packages), PBR materials, and named nodes. Each component becomes a toggleable node in GLB viewers. Also viewable directly on iOS/macOS (Apple Quick Look / AR).
+  - Digital twin pipeline: `fusion_export_usdz` → pull_file → `blender --background --python-expr "import bpy; bpy.ops.wm.usd_import(filepath='board.usdz'); bpy.ops.export_scene.gltf(filepath='board.glb')"`
+- **FBX** — Not available in current Fusion builds via the API. The command exists but fails clearly. Use `fusion_export_usdz` instead.
+- **DXF/DWG/OBJ/SKP** — Not available via the Fusion API (dialog-only). Commands exist but return clear errors with alternatives.
+
+##### 3D Viewport Captures
+- `fusion_take_screenshot` — Capture the Fusion viewport at any resolution without opening a dialog. Uses Fusion's render API (`saveAsImageFile`).
+  - Args: `outputPath` (required), `width` (default 1920), `height` (default 1080), `orientation` (optional)
+  - Orientations: `home`, `front`, `back`, `top`, `bottom`, `left`, `right`
+  - Example: Capture all 6 standard views for use as product images/icons:
+    ```bash
+    for orient in home front back top bottom left right; do
+      adom-bridge fusion_take_screenshot "{\"outputPath\": \"C:/tmp/3d-${orient}.png\", \"width\": 1920, \"height\": 1080, \"orientation\": \"${orient}\"}"
+    done
+    ```
+
+##### Electronics Source File Export (`fusion_export_source`)
+- `fusion_export_source` — Export the active electronics document as `.fsch`, `.fbrd`, or `.flbr` source file.
+  - Args: `outputPath` (required — full path with extension)
+  - The extension determines the format: `.fsch` (schematic), `.fbrd` (board), `.flbr` (library)
+  - Validates extension, creates output directory, verifies file was created, returns file size
+
+- **Full workflow to export both board and schematic from a cloud project:**
+  ```bash
+  # Step 1: Open the .fprj (NOT .fbrd/.fsch directly — those fail)
+  adom-bridge fusion_open_cloud_file '{"projectName":"Main", "fileName":"MyDesign", "fileExtension":"fprj", "folderPath":"Molecules/MyDesign"}'
+
+  # Step 2: Screenshot to check for blocking dialogs (always do this after open)
+  adom-bridge fusion_screenshot_fusion
+
+  # Step 3: Enter board view (MUST be Board Layout workspace, not 3D)
+  adom-bridge fusion_show_2d_board
+
+  # Step 4: Export .fbrd (board first — it's already in board view)
+  adom-bridge fusion_export_source '{"outputPath": "C:/tmp/exports/MyDesign.fbrd"}'
+
+  # Step 5: Switch to schematic (EDIT .s1 = first schematic sheet)
+  adom-bridge fusion_electron_run '{"command": "EDIT .s1"}'
+
+  # Step 6: Export .fsch
+  adom-bridge fusion_export_source '{"outputPath": "C:/tmp/exports/MyDesign.fsch"}'
+
+  # Step 7: Pull files to Docker
+  adom-bridge pull_file '{"filePaths":["C:/tmp/exports/MyDesign.fbrd","C:/tmp/exports/MyDesign.fsch"], "saveTo":"/tmp/exports"}'
+  ```
+
+- **Critical gotchas:**
+  - You MUST open the `.fprj` first — opening `.fbrd`/`.fsch` directly fails or triggers blocking dialogs
+  - You MUST call `fusion_show_2d_board` before exporting `.fbrd` (the Electronics Design overview won't work)
+  - Always export `.fbrd` FIRST (from board view), then switch to schematic for `.fsch`
+  - If export fails with "file not found", the wrong workspace is active — screenshot to verify
+  - After `fusion_open_cloud_file`, always screenshot to check for "Select Electronics Design File" dialog
+  - `WRITE` command is blocked — it opens a blocking save dialog. Use `fusion_export_source` instead
+
+- Note: `WRITE` is blocked — it opens a "Version Description" dialog on cloud docs even with a path argument (tested 2026-04-10). Use `fusion_save_to_cloud` to save to cloud, `fusion_export_source` for Fusion-format, or `fusion_export_eagle_source` for plain EAGLE format.
+
+##### Plain EAGLE Source Export (`fusion_export_eagle_source`)
+- `fusion_export_eagle_source` — Export the active electronics document as plain EAGLE XML `.sch` or `.brd`.
+  - Args: `outputPath` (required — full path ending in `.sch` or `.brd`)
+  - Internally: exports `.fsch`/`.fbrd` via `Document.CopyToDesktop`, then extracts the EAGLE XML from the ZIP container, cleans up the temp file.
+  - The output is valid EAGLE XML (`<?xml><eagle version="9.7.0">...`) parseable by standalone EAGLE, KiCad import, or any XML tool.
+  - Same workflow/prerequisites as `fusion_export_source` — just use `.sch`/`.brd` extensions instead of `.fsch`/`.fbrd`.
+
+  ```bash
+  # Board (.brd) — must be in PCB Editor / Board Layout
+  adom-bridge fusion_show_2d_board
+  adom-bridge fusion_export_eagle_source '{"outputPath": "C:/tmp/exports/MyDesign.brd"}'
+
+  # Schematic (.sch) — must be in Schematic Editor
+  adom-bridge fusion_electron_run '{"command": "EDIT .s1"}'
+  adom-bridge fusion_export_eagle_source '{"outputPath": "C:/tmp/exports/MyDesign.sch"}'
+  ```
+
+##### Dialog Dismissal (`fusion_close_window`)
+- `fusion_close_window` — Close a specific Fusion dialog by sending WM_CLOSE (equivalent to clicking X).
+  - Args: `hwnd` (required — from `fusion_window_info` or `fusion_dismiss_blocking_dialogs` remaining[])
+  - Works on dialogs that Escape doesn't close — e.g. "Recovered Documents"
+  - Does NOT force-kill — the dialog can still intercept WM_CLOSE
+
+##### Electronics Import (Round-Trip)
+- `fusion_import_electronics` — Import Fusion-native `.fsch`, `.fbrd`, or `.flbr` files as new local documents
+  - Uses `Document.newDesignFromLocal` under the hood
+  - Auto-screenshots after import (catches blocking dialogs)
+  - Args: `filePath` (required Windows path to .fsch, .fbrd, or .flbr)
+  - After import, use `fusion_save_to_cloud` to persist to Fusion cloud
+  - **`.fsch` import works standalone** — creates a new schematic project
+  - **`.fbrd` import may fail** — boards have external references to schematics/libraries. Error: "New design cannot be created from a local file containing external references"
+  - **`.flbr` import works standalone** — creates a new library project
+  - For legacy EAGLE files: use `fusion_open_schematic` (.sch), `fusion_open_board` (.brd), `fusion_open_lbr` (.lbr)
+
+##### Library Round-Trip Workflow
+Export and re-import Fusion electronics libraries:
+```bash
+# 1. Open library from cloud
+adom-bridge fusion_open_cloud_file '{"projectName":"Main","fileName":"Adom Common Components","folderPath":"Molecules/Libraries"}'
+
+# 2. Export as .flbr (Fusion-native binary) and .scr (EAGLE script text)
+adom-bridge fusion_save_lbr '{"outputPath":"C:/tmp/library.flbr"}'
+adom-bridge fusion_export_lbr '{"outputPath":"C:/tmp/library.scr"}'
+adom-bridge fusion_close_document
+
+# 3. Re-import the .flbr
+adom-bridge fusion_import_electronics '{"filePath":"C:/tmp/library.flbr"}'
+
+# 4. Verify symbols survived round-trip
+adom-bridge fusion_export_lbr '{"outputPath":"C:/tmp/library-verify.scr"}'
+
+# 5. Save to cloud with new name
+adom-bridge fusion_save_to_cloud '{"name":"Library-copy"}'
+```
+
+##### Demo Projects
+171+ electronics molecules are exported in the `adom-bridge-demo` repo (separate from adom-bridge).
+Three reference boards with full export formats:
+
+| Board | Cloud Path | Layers | Components | Files |
+|-------|-----------|--------|------------|-------|
+| DRV8411A | Main / Molecules / XRP / DRV8411A | 4 | 29 | 27 |
+| DRV8323SR | Main / Molecules / Experiments / MotorControl / DRV8323SR | 2 | 43 | 27 |
+| VL53L8BreakoutMolecule | Main / Molecules / XRP / TimeOfFlightVL53L8 / VL53L8BreakoutMolecule | 2 | 30 | 27 |
+
+Each folder contains: .fsch, .fbrd, bom.csv, cpl.csv, gerbers.zip, 6 board images, 7 3D renders (home/front/back/top/bottom/left/right), STEP, IGES, SAT, STL, 3MF, F3D, USDZ, board screenshot, 3D board screenshot.
+
+#### Cloud Document Management
+
+Manage Fusion 360 cloud documents (hub projects, files, versions). Required for 3D package workflows since EAGLE library 3D models are stored as cloud documents.
+
+- `fusion_save_to_cloud` -- Save the active Fusion document to the cloud. Args: `name` (required), `projectName` (optional, defaults to active project), `folderPath` (optional), `description` (optional). Returns: `fileId`, `versionNumber`, `wipUrn` (if cloud-hosted).
+- `fusion_list_cloud_projects` -- List all cloud projects in the user's hub. Returns array of `{name, id}` per hub.
+- `fusion_list_cloud_files` -- List files in a cloud project/folder. Args: `projectName` (optional), `folderPath` (optional). Returns: `files` array with `{name, id, versionNumber, fileExtension, dateModified}` and `subfolders` array.
+- `fusion_create_cloud_folder` -- Create a folder in a cloud project. Args: `folderName` (required), `projectName` (optional), `parentPath` (optional). Returns `folderId`. Idempotent — returns existing folder if it already exists.
+- `fusion_check_recovery` -- Check if a cloud file has a recovery document from a previous crash. Args: `fileName` (required), `projectName` (optional), `folderPath` (optional). Returns `hasRecovery: true/false`. Use this BEFORE opening files to avoid the blocking "Open recovery document instead?" dialog. If recovery exists, call `fusion_open_cloud_file` with `recovery: "open"` (restore unsaved work) or `recovery: "discard"` (delete recovery, open cloud version).
+- `fusion_open_cloud_file` -- Open a cloud file in Fusion by name. **If a recovery document exists and no `recovery` arg is given, the command STOPS and reports the recovery instead of opening** — you must decide whether to preserve or discard unsaved work. Args: `fileName` (required), `projectName` (optional), `folderPath` (optional), `recovery` ("open" = restore unsaved work, "discard" = delete recovery and open cloud version).
+- `fusion_export_cloud_file` -- Export the active Fusion document to a local file for transfer back to Docker. Args: `outputPath` (required), `format` (optional, default "step"). The exported file can then be pulled back to Docker via `pull_file`.
+- `fusion_delete_cloud_file` -- Delete a cloud file by name. Args: `fileName` (required), `projectName` (optional), `folderPath` (optional). File must not be open in Fusion — close it first with `fusion_close_document`.
+- `fusion_walk_cloud_tree` -- **Long-running.** BFS walk of a cloud folder tree. Returns a flat list of all files and folders. Runs entirely on the Fusion main thread — **blocks all other add-in commands** until done (check progress with `fusion_addin_status`).
+  - Args: `projectName` (optional), `folderPath` (optional, starting folder), `maxDepth` (default 10), `maxFolders` (default 500), `extensions` (optional list, e.g. `["f3d","fprj"]`), `nameContains` (optional substring filter), `includeFiles` (default true)
+  - Returns: `{project, rootFolder, folders[], files[], stats: {foldersVisited, foldersSkipped, filesFound, maxDepthReached, truncated}}`
+  - **Per-folder timeout (30s):** If a single folder's cloud API calls take >30s (common for large projects), the folder is skipped and counted in `foldersSkipped`. This prevents indefinite hangs.
+  - **Progress tracking:** While running, `fusion_addin_status` returns `walkProgress` with `{foldersVisited, filesFound, currentFolder, queueSize}` — poll this every 1–10s to monitor progress (see "Live folder progress streaming" below).
+  - **Non-blocking alternative:** Use `fusion_search_cloud_files` for targeted searches, or `fusion_list_cloud_files` for single-folder listings (these are faster but don't recurse).
+  - Example: `adom-bridge fusion_walk_cloud_tree '{"projectName":"Main","folderPath":"Molecules","nameContains":"DRV","extensions":["fprj"]}'`
+
+#### Live folder progress streaming with `watch`
+
+For long walks, use the built-in `watch` wrapper. It spawns the inner search command on a worker thread, polls `fusion_addin_status` internally, and emits one JSON event per line to stdout as the walker visits each folder. **No manual polling loop needed.**
+
+```bash
+adom-bridge watch '{"command":"fusion_walk_cloud_tree","args":{"projectName":"Main","folderPath":"Molecules","nameContains":"BQ25792"}}'
+```
+
+Output is one JSON object per line, three event types:
+
+```jsonl
+{"event":"started","command":"fusion_walk_cloud_tree","args":{...},"interval":2,"_hint":"streaming progress events follow, one per line, ending with 'complete' or 'error'"}
+{"event":"progress","busyCommand":"walk_cloud_tree","elapsedSeconds":15.0,"foldersVisited":14,"queueSize":50,"filesFound":0,"currentFolder":"Molecules/Sensing"}
+{"event":"progress","busyCommand":"walk_cloud_tree","elapsedSeconds":23.4,"foldersVisited":22,"queueSize":108,"filesFound":0,"currentFolder":"Molecules/Examples"}
+{"event":"progress","busyCommand":"walk_cloud_tree","elapsedSeconds":31.8,"foldersVisited":30,"queueSize":100,"filesFound":0,"currentFolder":"Molecules/RAPID NAME TAGS/Connor Wood"}
+... (one per real change in walkProgress, deduped) ...
+{"event":"complete","result":{"folders":[...],"files":[...],"stats":{"foldersVisited":169,"filesFound":12,"truncated":false}}}
+```
+
+Read stdout line-by-line. Stop when you see `event:complete` or `event:error`. The full final result is in the `complete` event's `result` field.
+
+**Optional `interval` arg** (default 2s, clamped to [1, 30]):
+
+```bash
+adom-bridge watch '{"command":"fusion_walk_cloud_tree","args":{...},"interval":1}'
+```
+
+**For Claude Code consumers**: pipe `watch` directly into the `Monitor` tool. Each JSON line becomes a real-time event notification in the chat — you (and the user) see folder names appear one-by-one as the walker visits them. No bash loop, no `disown`, no subprocess gymnastics. Verified live in 1.3.16 on a 169-folder walk that returned all 12 BQ25792 cloud files cleanly.
+
+**Watchable commands** (whitelist): `fusion_walk_cloud_tree`, `fusion_search_cloud_files`. Other commands return `success:false` with a `_hint` listing the watchable set.
+
+**When NOT to use watch**: short single-folder operations (`fusion_list_cloud_files`, `fusion_open_cloud_file`) — those return in <2s and don't need streaming. The `watch` wrapper is purely for the long BFS commands.
+- `fusion_search_cloud_files` -- **Long-running.** Recursive substring search on file names across cloud folders. v1.0.2+ of the add-in adds: per-folder timeout, doEvents() every 50 files, per-file try/except, iterative BFS, and a stale-lock watchdog — Fusion stays responsive throughout (no "Not Responding" freeze).
+  - **Args (no hard upper caps in v1.0.2+):** `query` (required, substring, case-insensitive), `projectName` (optional, defaults to active), `folderPath` (optional starting subfolder — **narrow with this**), `recursive` (default false), `maxDepth` (default 2), `maxFolders` (default 10), `maxResults` (default 20), `folderTimeout` (default 30s), `searchTimeout` (default 120s), `timeout` (HTTP envelope, default 620s).
+  - **Before calling:** if the user knows roughly where the file is (e.g. customer-named folder), **ask them**. Naming a subfolder cuts 5-40 min searches down to ~10s.
+  - **Why slow:** Autodesk's free Fusion 360 Python API has no indexed file-search endpoint. We walk the Data API one folder at a time — each = one HTTP round-trip to Autodesk. **This is an Autodesk API limitation, not adom-bridge's.** When telling the user the search is taking a while, attribute it to Autodesk / Fusion 360, not to adom-bridge's bridge. **There is now a FAST native alternative — `aps_search` (see "APS — fast indexed cloud search" below).** It hits Autodesk Platform Services' indexed Data Management API and returns ~instantly, even when Fusion is CLOSED. Call `aps_status` first; if `configured:true`, prefer `aps_search` and only fall back to this folder-walking verb when APS isn't set up.
+  - **Interpreting results (critical for no-false-negatives):** the response contains `searchComplete` (bool), `foldersSkipped`, `filesSkipped`, `truncated`, `folderLimitReached`, `searchTimedOut`. `searchComplete:true` ONLY when **all five** are clean — that's the confidence flag. If `searchComplete:false`, the search hit a cap before exhausting the scope; **don't report "file not found"** — re-run with broader caps OR narrower `folderPath`.
+  - **Case sensitivity:** fully case-insensitive both directions (query and file names lowercased). Substring match, not whole-word — `"cosm"` matches `COSMIIC`, `COSMOCOIL`, etc.
+  - **Cost feedback in response:** `costAnalysis: {elapsedSeconds, foldersPerSecond, estimatedSecondsPer100Folders}` so the AI can budget the next search realistically.
+  - **Real numbers from a live test:** searching `Main/Molecules` recursively (173 folders deep, max 8 depth) for "cosmiic" returned in 168 s with `searchComplete:true, totalFound:3`. Fusion stayed `main_thread:responsive` throughout.
+  - **Pair with `watch`** for streaming progress updates: see below.
+
+#### APS — fast indexed cloud search (v1.8.182+)
+
+`aps_search` is a **native, ~instant** alternative to the folder-walking `fusion_search_cloud_files`. It queries **Autodesk Platform Services** (APS, formerly Forge) **Data Management API**, which has a real server-side index — so a search that takes minutes by folder-walking returns in well under a second, and it works **even when Fusion 360 is closed** (it's pure HTTPS, no bridge required). adom-bridge runs its own 3-legged **PKCE** OAuth, so the user's APS **client secret never leaves their machine**.
+
+**One-time setup (user side):**
+1. Register a free app at <https://aps.autodesk.com> → enable the **Data Management API**.
+2. Set the app's **Callback URL** to exactly `http://localhost:8910/aps/callback`.
+3. Put the **Client ID** in ab config key `aps_client_id` (in `~/.adom/config.json`) or via Settings.
+4. Run `aps_auth` once — it opens the system browser for Autodesk sign-in. Tokens cache in `~/.adom/aps_tokens.json` and auto-refresh; you won't be prompted again.
+
+**Verbs:**
+- `aps_status` — **call this first.** Non-prompting. Returns `{configured, signedIn}`. `configured:false` → no client id; use `fusion_search_cloud_files`. `configured:true, signedIn:false` → run `aps_auth`. Both true → `aps_search` is ready.
+- `aps_auth` — interactive sign-in (opens browser). One-time per device.
+- `aps_hubs` — `{hubs[]{id,name}}` (your Autodesk teams).
+- `aps_projects {hubId?}` — `{hubId, projects[]{id,name}}` (default: first hub).
+- `aps_search {query, projectName?, projectId?, hubId?}` — `{query, hubId, count, results[]{name,id,type,lastModified,project}}`. `query` is a case-insensitive substring of the file's displayName. Without `projectName`/`projectId` it searches up to 8 projects in the hub. Open a hit with `fusion_open_cloud_file {fileName, projectName}`.
+
+**Decision flow for an AI doing a cloud file search:** `aps_status` → if `configured` (sign in with `aps_auth` if needed) use `aps_search`; else fall back to `fusion_search_cloud_files` and tell the user that registering a free APS app (above) would make future searches instant.
+
+**Export formats for `fusion_export_cloud_file`:**
+
+| Format | Extension | Use case |
+|--------|-----------|----------|
+| `step` | .step | Industry-standard CAD interchange (default) |
+| `stl` | .stl | 3D printing, mesh-based |
+| `f3d` | .f3d | Fusion 360 native archive (preserves all features) |
+| `iges` | .iges | Legacy CAD interchange |
+| `sat` | .sat | ACIS solid modeling kernel format |
+| `smt` | .smt | Parasolid format |
+
+Also supported for import via `fusion_import_step`: STEP (.step/.stp), STL (.stl), IGES (.iges/.igs), SAT (.sat), SMT (.smt), OBJ (.obj), F3D (.f3d).
+
+**Round-trip: workspace → Fusion Cloud → workspace**
+
+```bash
+# === workspace to Fusion Cloud ===
+# 1. Send file from Docker to Windows desktop
+adom-bridge send_files '{"files": [{"path": "/home/user/component.step"}]}'
+# 2. Import into Fusion
+adom-bridge fusion_import_step '{"filePath": "C:/Users/john/Downloads/component.step"}'
+# 3. Save to cloud (gets a wip_urn for 3D library linking)
+adom-bridge fusion_save_to_cloud '{"name": "my-component", "projectName": "Personal"}'
+
+# === Fusion Cloud to Docker ===
+# 1. Find and open the cloud file
+adom-bridge fusion_walk_cloud_tree '{"projectName": "Personal", "nameContains": "my-component"}'
+adom-bridge fusion_open_cloud_file '{"fileName": "my-component", "projectName": "Personal"}'
+# 2. Export to local filesystem
+adom-bridge fusion_export_cloud_file '{"outputPath": "C:/tmp/export/my-component.step", "format": "step"}'
+# 3. Pull back to Docker
+adom-bridge pull_file '{"path": "C:/tmp/export/my-component.step"}'
+
+# === Cloud management ===
+adom-bridge fusion_list_cloud_projects '{}'
+adom-bridge fusion_create_cloud_folder '{"folderName": "Electronics", "projectName": "Main"}'
+adom-bridge fusion_list_cloud_files '{"projectName": "Main", "folderPath": "Electronics"}'
+adom-bridge fusion_delete_cloud_file '{"fileName": "old-file", "projectName": "Main"}'
+```
+
+#### Manufacturing Exports (Gerbers, BOM, CPL)
+
+Export manufacturing files from an open PCB board — everything needed to fabricate boards and assemble components via Adom's PCBA service. **All manufacturing commands require a .brd board open in PCB Editor** (use `fusion_open_board` or `fusion_show_2d_board`).
+
+**Recommended workflow order:** `detect_layers` → `set_design_rules` → DRC → `export_gerbers` → `export_bom` → `export_cpl` → `pull_file` all back to Docker.
+
+Every manufacturing command returns structured JSON with:
+- `message` — AI-oriented summary explaining what was produced and why it matters
+- `nextSteps[]` — ordered list of what to run next in the manufacturing pipeline
+- `hint` — tips for interpreting results or recovering from issues
+- `data` — structured metadata (paths, counts, layer info) for programmatic use
+
+**Decision guide — which command to run:**
+- **Don't know the layer count?** → Run `fusion_detect_layers` first
+- **Need to check if the board meets fab specs?** → Run `fusion_set_design_rules` then DRC
+- **Ready to generate fab files?** → Run `fusion_export_gerbers`, then `fusion_export_bom`, then `fusion_export_cpl`
+- **Need visual review before export?** → Run `fusion_export_board_image` with preset `assembly_top` or `fabrication`
+- **Something failed?** → Check `data.hint` and `data.recoverySteps` in the error response
+
+**Commands:**
+
+- `fusion_detect_layers` -- Detect if the open board is 2-layer or 4-layer. Uses ULP script (primary) and CAM comparison (fallback). Returns `layerCount`, `copperLayers[]`, `method` (how it was detected), and `nextSteps[]`. **Run this first** — all other manufacturing commands auto-detect layers too, but running this explicitly gives you the data before committing to exports.
+
+- `fusion_set_design_rules` -- Apply Adom's JLCPCB-derived design rules (.edru XML files) to the open board. Auto-detects 2-layer vs 4-layer and loads the appropriate rule set. Returns `description` (human-readable rule summary), `edruFile`, and `nextSteps[]`.
+  - `action`: `"apply"` (default) loads rules into the board; `"export"` saves current board rules to a file; `"show"` displays rule capabilities without modifying anything
+  - `layers`: `"auto"` (default), `"2"`, or `"4"` — force a specific rule set
+  - After applying: run `fusion_electron_run '{"command": "DRC"}'` to check for violations. DRC markers appear in the board editor.
+
+- `fusion_apply_instapcb_rules` -- Convenience wrapper that applies the bundled Adom InstaPCB design rule sets without needing a local `.edru` file. Args: `layers` (`"2"` or `"4"`). Sends the bundled `.edru` from Docker to Windows automatically and loads it via the EAGLE `drc load` command. Use this instead of `fusion_set_design_rules` when you just want Adom's standard 2-layer or 4-layer InstaPCB rules.
+
+- `fusion_load_design_rules` -- Generic loader for ANY custom `.edru` file by path. Args: `filePath`. Use this for third-party fab vendor rules (JLCPCB, PCBWay, OSHPark, etc.) that the user has on disk.
+
+- `fusion_export_gerbers` -- Export Gerber (RS-274X) + Excellon drill files as a ZIP. Auto-detects 2-layer vs 4-layer and selects the correct JLCPCB-compatible CAM job. Returns `zipPath`, `zipSizeKB`, `files[]` (list of gerber files in the ZIP with sizes), `layerCount`, and `nextSteps[]`.
+  - `outputDir`: directory for the output ZIP (default: `C:/tmp/adom-gerbers/`)
+  - `boardName`: prefix for the ZIP filename (default: from active document name)
+  - `layers`: `"auto"` (default), `"2"`, or `"4"` — force CAM job selection
+  - Output ZIP contains: GTL, GBL (copper), GTS, GBS (solder mask), GTP, GBP (paste), GTO, GBO (silkscreen), GKO (outline), XLN (drill). 4-layer boards also get G1, G2 (inner copper).
+
+- `fusion_export_bom` -- Export Bill of Materials as CSV. Groups identical parts by value+package with quantity counts. Returns `componentCount`, `uniquePartCount`, and `nextSteps[]`.
+  - `outputPath`: (default: `C:/tmp/adom-bom.csv`)
+  - `grouped`: `true` (default) groups by value+package; `false` lists every component individually
+  - Output columns: Comment, Designator, Footprint, Quantity, Library — compatible with JLCPCB, PCBWay, Mouser, Digi-Key.
+
+- `fusion_export_cpl` -- Export Component Placement List (pick-and-place) as CSV. Returns `totalPlacements`, `topCount`, `bottomCount`, and `nextSteps[]`.
+  - `outputPath`: (default: `C:/tmp/adom-cpl.csv`)
+  - `side`: `"all"` (default), `"top"`, or `"bottom"` — filter for single-sided assembly
+  - Output columns: Designator, Mid X, Mid Y, Layer, Rotation — coordinates in mm.
+
+- `fusion_export_board_image` -- Export PNG image of the board with layer presets. Returns `fileSize`, `preset`, and `nextSteps[]`.
+  - `outputPath`: (default: `C:/tmp/adom-board.png`)
+  - `dpi`: resolution (default: 300, max: 600)
+  - `preset`: layer preset name (see table below)
+  - `layers`: custom layer numbers as int array — overrides preset
+  - `monochrome`: `true` for black & white
+  - `listPresets`: set `true` to get available presets instead of exporting
+
+**Layer presets for `fusion_export_board_image`:**
+
+| Preset | Layers | Description |
+|--------|--------|-------------|
+| `all` | All | Every layer visible |
+| `top_copper` | 1, 17, 18 | Top copper + pads + vias |
+| `bottom_copper` | 16, 17, 18 | Bottom copper + pads + vias |
+| `top_silkscreen` | 21, 25 | Top silkscreen + component names |
+| `bottom_silkscreen` | 22, 26 | Bottom silkscreen + component names |
+| `top_soldermask` | 29 | Top solder mask openings |
+| `bottom_soldermask` | 30 | Bottom solder mask openings |
+| `top_paste` | 31 | Top paste/stencil openings |
+| `bottom_paste` | 32 | Bottom paste/stencil openings |
+| `board_outline` | 20 | Board outline (dimension layer) |
+| `drill` | 44, 45, 17, 18 | Drill holes + vias |
+| `assembly_top` | 1, 17, 18, 20, 21, 25, 51 | Top assembly — copper + silk + outline |
+| `assembly_bottom` | 16, 17, 18, 20, 22, 26, 52 | Bottom assembly — copper + silk + outline |
+| `fabrication` | 1, 16, 17–20, 21, 22, 25, 26, 29, 30, 51 | Full fabrication view |
+
+**Adom InstapcbPCB manufacturing capabilities (used by `fusion_set_design_rules`):**
+
+| Parameter | Metric | Imperial |
+|-----------|--------|----------|
+| Layers | 1, 2, 4, 6 | — |
+| Min trace width | 0.08mm | 3 mil |
+| Min trace spacing | 0.08mm | 3 mil |
+| Min via drill | 0.2mm | 8 mil |
+| Min silkscreen text | 0.1mm | 4 mil |
+| Board edge clearance | 0.05mm | 2 mil |
+| Board thickness | 1.6mm | 63 mil |
+| Copper weight | 0.5 oz (17.5 μm) | — |
+| Solder mask | Green | — |
+| Surface finish | HASL / ENIG | — |
+| Turnaround | 4 hours (fab + assembly) | — |
+
+**Manufacturing workflow — Fusion to Adom PCBA:**
+
+```bash
+# 1. Open the board
+adom-bridge fusion_open_board '{"filePath": "C:/projects/myboard.brd"}'
+
+# 2. Detect layer count (auto-selects 2-layer or 4-layer rules/CAM)
+adom-bridge fusion_detect_layers
+
+# 3. Apply Adom design rules for the detected layer count + run DRC
+adom-bridge fusion_set_design_rules '{"action": "apply"}'
+adom-bridge fusion_electron_run '{"command": "DRC"}'
+
+# 4. Export manufacturing files (gerbers auto-select correct CAM job)
+adom-bridge fusion_export_gerbers '{"outputDir": "C:/tmp/mfg"}'
+adom-bridge fusion_export_bom '{"outputPath": "C:/tmp/mfg/bom.csv"}'
+adom-bridge fusion_export_cpl '{"outputPath": "C:/tmp/mfg/cpl.csv"}'
+
+# 5. Export board images for review
+adom-bridge fusion_export_board_image '{"outputPath": "C:/tmp/mfg/top-copper.png", "preset": "top_copper"}'
+adom-bridge fusion_export_board_image '{"outputPath": "C:/tmp/mfg/assembly-top.png", "preset": "assembly_top"}'
+adom-bridge fusion_export_board_image '{"outputPath": "C:/tmp/mfg/board-outline.png", "preset": "board_outline"}'
+
+# 6. Pull files back to Docker for Adom PCBA ordering
+adom-bridge pull_file '{"path": "C:/tmp/mfg/bom.csv"}'
+adom-bridge pull_file '{"path": "C:/tmp/mfg/cpl.csv"}'
+```
+
+### Desktop Tools
+
+- `desktop_close_window` -- Gracefully close a window (WM_CLOSE, so save prompts fire). Resolves `hwnd` or `titleContains`; optional `forceAfterMs` kills the owning process only if the window outlives the grace period. Returns MEASURED `closed`/`forced`. Prefer this over process_kill for anything with unsaved state.
+- `desktop_wait_for_window` -- Block (bounded timeout) until a window matching `titleContains`/`className`/`pid` appears, or with `state:"absent"` until it goes away (a dialog dismissed, an app exited). The honest replacement for sleep-and-rescreenshot loops: `adom-bridge desktop_wait_for_window '{"titleContains":"Save As","timeoutMs":10000}'`.
+- `desktop_open_folder` -- Open a file or folder in Windows Explorer. If given a file path, Explorer opens with the file highlighted (selected). Args: `path` (file or folder path).
+- `desktop_open_url` -- Open a URL in the user's **NATIVE OS BROWSER** — i.e. the real Edge / Chrome / Firefox / Brave they use every day, with their saved logins, history, bookmarks, and extensions. This is NOT pup, NOT Chrome for Testing — it's the browser the human actually uses. Hand it off when the user needs to interact with a logged-in account themselves.
+  - Args: `url` (required string), `browser` (optional: `"default"` (Windows-registered default — could be Edge, Chrome, Firefox, Brave; whatever they set), `"chrome"`, `"edge"`, `"firefox"`, `"brave"`).
+  - Examples:
+    - `adom-bridge desktop_open_url '{"url":"https://claude.ai/"}'` -- opens in user's default native browser, already signed in
+    - `adom-bridge desktop_open_url '{"url":"https://docs.example.com","browser":"edge"}'` -- force native Edge
+  - Returns `{ok, browser, url, exePath?}`. Allowed schemes: http, https, mailto, ftp, ftps. Other schemes refused.
+
+#### `desktop_open_url` vs `pup_open_window` — two completely different browsers
+
+| | `desktop_open_url` | `pup_open_window` |
+|---|---|---|
+| **What browser** | Native OS browser the user uses daily — Microsoft Edge / Google Chrome / Mozilla Firefox / Brave (whichever they've set as Windows default, or the one you name explicitly) | Puppeteer-controlled **Chrome for Testing** — a separate Chromium build that pup launches |
+| **Profile / data** | The user's real profile: saved logins, history, bookmarks, extensions, autofill | Isolated profile under `plugins/puppeteer/profiles/<sessionId>/` — empty, no saved logins |
+| **Who interacts with the page** | The HUMAN. Claude hands the URL off and is done. | CLAUDE drives it programmatically — screenshots, clicks, eval, recording. The human just watches. |
+| **Use when** | A login is required (claude.ai, GitHub, internal tools, banking) — the human's existing session must be reused | Automation, scraping, screenshot capture, video recording, headful UI testing |
+| **Can Claude control it after launch?** | No — once handed off, Claude can't see or drive it | Yes — every `pup_*` verb (screenshot, eval, navigate, record, etc.) |
+
+**Decision rule:** human-in-the-loop login flow → `desktop_open_url`. AI-driven automation → `pup_open_window` (defaults to Chrome for Testing). AI-driven automation that **must** be the user's real, signed-in profile (GCP Console with org/projects, internal SSO behind a managed-Chrome policy, anything Context-Aware Access blocks for non-enrolled browsers) → `pup_open_window` with the new `nativeBrowser` + `nativeProfile` args (v1.0.5+, see below).
+
+#### When pup means "the user's real Chrome/Edge" — `pup_open_window` native mode (v1.0.6+, smart flow v1.0.11)
+
+Default `pup_open_window` (no native args) launches Chrome for Testing — same as day one. **Never auto-switch a plain pup request to native.** "Open this URL in pup", "screenshot this", "click that button" all stay on CfT.
+
+Native mode drives the user's **REAL browser** — their actual signed-in profile, with live cookies, org policies, and device enrollment intact (NOT a clone — v1.0.6 replaced the old clone approach). Opt-in via TWO additive args from `desktop_list_browsers`:
+
+```bash
+adom-bridge desktop_list_browsers     # installed browsers + profiles (+ the signed-in account per profile)
+adom-bridge pup_open_window '{
+  "sessionId":"gcp",
+  "nativeBrowser":"chrome",            # chrome / edge / brave
+  "nativeProfile":"Default",           # profile id: Default / Profile 1 / Profile 2
+  "url":"https://console.cloud.google.com"
+}'
+```
+
+**The smart flow.** CDP (the protocol pup drives) needs the browser running with `--remote-debugging-port`, which can only be set at launch. So the bridge handles each situation differently and tells you which happened:
+
+| Situation | What ab does | Response |
+|---|---|---|
+| Already driving that browser+profile | Reuse the live connection | `ok` + `narrative` |
+| Running **with** a debug port (power-user launched it that way, or ab did earlier) | Connect, no relaunch | `ok` + `narrative` |
+| **Not running at all** | **Launch it fresh with the debug port — NO prompt** (nothing to disrupt) | `ok`, `launchedFresh:true` + `narrative` — just proceed |
+| **Open without** a debug port | **Ask the user** — ab must close+reopen it | `errorCode:"native_relaunch_required"` + `confirmArgs` + `alternatives` |
+| Debug port **refuses to bind** (enterprise policy) | Won't close it again | `errorCode:"native_cdp_blocked"` + `diagnosis` + `alternatives` |
+
+**Handling the two consent/blocked codes:**
+
+- **`native_relaunch_required`** — the browser is open without the port, so driving it means closing + reopening it (with `--restore-last-session`, so all tabs/windows come back). **Ask the user's permission**, then re-call with `"nativeRelaunch":true`. The response's `alternatives` lists other installed browsers you could offer instead.
+- **`native_cdp_blocked`** — the debug port won't open, almost always an **enterprise policy** (`RemoteDebuggingAllowed` disabled via Google Workspace / Chrome cloud management — affects **Chrome browser-wide, every profile**). `diagnosis` says whether it's a confirmed local-registry policy or a likely cloud-managed one. ab will **not** close that browser again. `alternatives` names other installed browsers — **Edge usually escapes Google management**, so it often drives natively when Chrome can't. Offer the user the alternative, or fall back to generic CfT.
+
+**Always available — generic CfT.** `pup_open_window` with NO `nativeBrowser`/`nativeProfile` drives a clean Chrome-for-Testing instance: no user session, no managed policy, fully controllable. If a task needs the user's logged-in session there, have them sign in once. This is the universal fallback whenever native is blocked.
+
+**Power-user shortcut:** if the user launches their browser at startup with `--remote-debugging-port=<N>`, ab reconnects every session with no prompt at all (a productized opt-in "keep native browsers debug-ready at boot" is on the roadmap, default OFF for security).
+
+**Routing rule — DON'T auto-escalate.** Treat native as opt-in:
+
+| User says | What to do |
+|---|---|
+| "pup" / "open in pup" / screenshot / eval / debug | DEFAULT pup (CfT). Never mention profiles. |
+| "native chrome" / "my real browser" / "my work profile" / "my `<account>` profile" | Native. Call `desktop_list_browsers`. If exactly one profile clearly fits the request, use it and say which one ("opening in your `[email protected]` profile on Chrome"). If multiple profiles could fit (e.g. a `google.com` URL with both `[email protected]` and `[email protected]` profiles signed in), **ASK** ("Which profile — work `[email protected]` or personal `[email protected]`?") and then drive that pair. |
+| anything else | Default pup. |
+
+**Anti-fingerprint:** native sessions launch without `--enable-automation` and with `--disable-blink-features=AutomationControlled`. `navigator.webdriver === false`. No "controlled by automated software" banner. Sites that probe for automation see a normal browser.
+
+**Firefox** appears in `desktop_list_browsers` but is rejected for native drive with `errorCode:"firefox_no_cdp"` — Firefox doesn't speak the Chrome DevTools Protocol, so puppeteer can't drive it. If the user wants Firefox, hand off via `desktop_open_url` instead.
+
+**Native-mode error codes:**
+- `native_relaunch_required` — browser open without a port; ask the user, re-call with `nativeRelaunch:true` (see the smart-flow table above).
+- `native_cdp_blocked` — debug port policy-blocked; read `diagnosis`, offer `alternatives` or generic CfT (see above).
+- `firefox_no_cdp` — caller passed `nativeBrowser:"firefox"`. Firefox doesn't speak CDP; hand off via `desktop_open_url`.
+- `native_browser_not_installed` — that browser isn't installed on this machine.
+- `native_user_data_missing` — installed but never launched, so the User Data dir doesn't exist yet. Ask the user to open it once.
+- `native_profile_not_found` — `nativeProfile` isn't a real profile id under this browser's User Data. Call `desktop_list_browsers` to see what's valid.
+
+#### ⚠️ Common footgun — `localhost` / `file://` URLs from Docker AIs
+
+If you're running this CLI from a remote Docker container (galliaApril, dartv4, etc.), `pup_open_window` / `pup_open_tab` / `pup_navigate` will load the URL inside the USER's local pup — NOT inside your container. So a URL like `http://localhost:8080/foo.html` resolves to the user's machine, not your container's service.
+
+**v1.7.10+ detects this.** When you pass a URL whose host is `localhost`, `127.0.0.1`, `0.0.0.0`, `::1`, or scheme is `file://`, the response includes a `_hint` field explaining the issue and suggesting the public-slug URL pattern (`https://<user>-<repo>-<suffix>.adom.cloud/proxy/<port>/<path>`). **The call still proceeds** — rare legitimate cases exist where the user actually does have something running on their localhost.
+
+**Recipe — load something from inside your container into pup:**
+
+```bash
+# 1. Start your service inside the container (e.g. a local HTML viewer):
+python3 -m http.server 8786 --bind 0.0.0.0 &
+
+# 2. Ask your USER for the container's adom.cloud slug suffix
+#    (look at their browser URL when they open hydrogen or claude.ai/code).
+#    Slug looks like: <username>-<container>-<random-id>
+
+# 3. Open the public URL — NOT localhost:
+adom-bridge pup_open_window '{
+  "sessionId":"demo",
+  "url":"https://<your-container-slug>.adom.cloud/proxy/8786/foo.html"
+}'
+```
+
+If you don't have the suffix handy, just ask the user. Or if the file you wanted to show pup is one your container already wrote to disk, push it to a public location (wiki asset, S3) and load from there.
+
+
+- `desktop_bring_to_front` -- Bring a window to the foreground by HWND or title substring. Uses keybd_event + AttachThreadInput to bypass Windows foreground lock. Preserves maximized state.
+  - Args: `hwnd` (int) OR `titleContains` (string, case-insensitive). One required.
+  - Example: `adom-bridge desktop_bring_to_front '{"titleContains": "Fusion"}'`
+- `desktop_set_window_state` -- Change a window's show state without bringing it to the foreground (or both, if combined with `desktop_bring_to_front`). Args: `hwnd` (int) OR `titleContains` (string) OR `cacheKey`, plus `state` (one of `"maximize"`, `"minimize"`, `"restore"`, `"show"`, `"hide"`, `"bottom"`). Use to ensure Fusion or KiCad windows are maximized for screenshots, or to hide noisy background windows during demos.
+  - Example: `adom-bridge desktop_set_window_state '{"hwnd":133560,"state":"maximize"}'`
+  - **`state:"bottom"` (v1.9.114) -- z-order send-to-back, background.** Drops the window BEHIND all others without focusing, moving, or resizing it (`SetWindowPos HWND_BOTTOM` + `SWP_NOMOVE|SWP_NOSIZE|SWP_NOACTIVATE`); works even on an off-screen window. It's an ATOMIC check-and-demote: it reads `GetForegroundWindow()` first, and if the target IS the OS foreground (the user is interacting with it) it SKIPS the demotion and returns `wasForeground:true, sentToBack:false` so the caller backs off with no race; otherwise `wasForeground:false, sentToBack:true`. Use to park a background window behind the user's windows (still on-screen, taskbar-clickable, rendering for screenshots) without stealing focus.
+  - **`force:true` (v1.9.115)** sends it to back EVEN IF the window is currently the OS foreground (still no activation change; `sentToBack:true` always, `wasForeground` still reported). Use at window-LAUNCH time: Windows reassigns the foreground to a brand-new window when the previous foreground is destroyed, so "foreground at launch" is not a real user signal.
+  - Example: `adom-bridge desktop_set_window_state '{"titleContains":"(session: abc","state":"bottom","force":true}'`
+
+#### Real OS input — mouse + keyboard (v1.8.170+)
+
+`desktop_click` / `desktop_double_click` / `desktop_right_click` / `desktop_hover` / `desktop_type` / `desktop_press_key` synthesize **real OS input via `SendInput`** — so they land on **`chrome://` pages and native dialogs that browser CDP (`nbrowser_*` / `pup_*`) cannot reach**. The verb names mirror the browser extension's `nbrowser_*` so the model transfers between in-page and whole-desktop driving.
+
+- **You must say WHY (v2.0.84).** Every verb that takes over the screen - the four mouse verbs, `desktop_type`, `desktop_press_key`/`send_keys`, `desktop_bring_to_front`, `desktop_raise_window` - requires a **`reason`** from a relay caller, or it is refused with `errorCode:"reason_required"`. The reason is not for the log: ab renders **"`<your thread>`: `<your reason>`"** on the user's screen next to the glowing cursor, at the moment their machine moves. Write it for the human watching, not for a log line - `reason:"clicking Next on the Altium installer"`, not `reason:"sending a click"`.
+- **Gated behind shell-auto-approve** (same risk class as `shell_execute` — keystrokes/clicks hit whatever is focused on the user's live machine). If it's off you get `errorCode:"input_not_approved"`. **You (a cloud/relay AI) can't grant it yourself (v1.9.90)** — call `request_shell_approval` (or let the refusal auto-surface the prompt) and ask the user to click Approve / Bypass Permissions in Adom Bridge, then retry. Every action is written to the activity log.
+- **Focus a window first** by passing `{window:"<title substring>"}` (alias `titleContains`) or `{hwnd:<int>}` — reuses `desktop_find_window`'s resolver, so input lands on the intended window, not whatever happened to be focused. Get the hwnd from `desktop_list_windows` / `desktop_find_window`.
+- **Coords are physical screen pixels** — the same space as `desktop_list_windows` rects.
+
+**The four verbs that MOVE THE MOUSE each answer to a `mouse_*` name too (v2.0.84).** They are the same verbs, not new ones - the pointer verbs were named after what they do to a control (`click`, `hover`), so searching a verb list for "mouse" found nothing that moves the mouse. Use whichever name you reach for:
+
+| moves the mouse | alias |
+|---|---|
+| `desktop_hover` (also `desktop_move`) | `desktop_mouse_move` |
+| `desktop_click` | `desktop_mouse_click` |
+| `desktop_double_click` | `desktop_mouse_double_click` |
+| `desktop_right_click` | `desktop_mouse_right_click` |
+
+An alias is gated exactly like the verb it aliases - it is not a way around the reason requirement below.
+
+Verbs:
+- `desktop_click {x, y, button?:"left"|"right"|"middle", double?, window?|hwnd?}` — left-click by default. `desktop_double_click` / `desktop_right_click` are wrappers; `desktop_hover` moves the cursor without clicking (reveals tooltips).
+- `desktop_type {text, window?|hwnd?}` — types a literal Unicode string (`KEYEVENTF_UNICODE`, any keyboard layout).
+- `desktop_press_key {keys:[...], repeat?, window?|hwnd?}` (alias `desktop_send_keys`) — chords/shortcuts. Modifiers `ctrl/alt/shift/win`; named keys `enter/tab/esc/space/backspace/delete/insert/home/end/pgup/pgdn/up/down/left/right/f1-f12`.
+
+Canonical "navigate a browser to a URL" flow (works on `chrome://` where CDP can't):
+```bash
+adom-bridge desktop_press_key '{"keys":["ctrl+l"],"window":"Edge"}'   # focus Edge + select the address bar
+adom-bridge desktop_type        '{"text":"edge://extensions","window":"Edge"}'
+adom-bridge desktop_press_key   '{"keys":["enter"],"window":"Edge"}'
+```
+For a control that isn't reachable by CDP/coords (e.g. the Reload button on `edge://extensions`, which lives in a shadow DOM), Tab-navigate to it then Enter: `desktop_press_key {"keys":["tab","tab","enter"]}`.
+
+**Visual "Adom cursor" (v1.8.171+)** — a click-through teal cursor + a label that narrates what you're driving (trust cue; byte-faithful to the browser extension's cursor). Pure visual, *not* gated:
+- `desktop_cursor {action:"show"|"move"|"hide", x, y, label}` — drive/narrate the cursor on its own ("watch me"). Returns the overlay `hwnd`.
+- **On by default since v2.0.84** on `desktop_click`/`desktop_double_click`/`desktop_right_click`/`desktop_hover` (and their `mouse_*` aliases): ab glides the teal cursor to the target *then* does the real click, so the human always sees Adom is driving rather than an unattributed pointer jump. Pass `label:"Clicking Reload"` to narrate it in your own words; with no label it shows "`<your thread>`: `<your reason>`". Pass `cursor:false` only when the pointer move must be invisible. It was opt-in before, which meant the user lost the signal precisely when an AI was careless.
+- **Auto-hide (v1.8.174+):** the cursor hides itself after `ttlMs` (default **60s**) so it never lingers on the user's screen if you forget to hide it. Each `show`/`move` refreshes the timer. Pass `ttlMs:<ms>` (≤600000) for longer, or `persist:true` to keep it until you explicitly `desktop_cursor {action:"hide"}`. If a cursor you showed was auto-hidden, the **next** cursor/click response prefixes its `_hint` with a NOTE so you learn (no chatty unsolicited message).
+
+#### Background input via UI Automation (v1.8.174+) — no foreground, no focus steal
+
+The mouse/keyboard verbs above use `SendInput` = real OS input, which only lands on the **foreground** window — so ab foregrounds the target first, yanking it in front of the user's work. When you must NOT steal focus, use **UI Automation** instead: `InvokePattern.Invoke()` / `ValuePattern.SetValue()` are **programmatic** — the app services them via its accessibility tree with **no cursor move, no focus change, no foregrounding**. Chromium/Edge expose their a11y tree to UIA, so `chrome://` page buttons/links are reachable **by accessible name** (not coordinates).
+
+- `desktop_find_control {window|hwnd, name|contains, role?}` — **read-only** discovery (ungated). Returns `best:{name, automationId, role, rect, invokable, settable}`. Call this first to learn whether a control is UIA-reachable.
+- `desktop_ui_click {window|hwnd, name|contains, role?}` — UIA **Invoke** by accessible name, in the background. Gated behind shell-auto-approve.
+- `desktop_ui_set {window|hwnd, name|contains, text}` — UIA **SetValue** on a text field, in the background. Gated.
+
+`role` ∈ `button|edit|link|checkbox|menuitem|tab|listitem|combobox|radiobutton|document|group|spinner`. **Caveat (surfaced in `_hint`, not hidden):** some shadow-DOM controls aren't in the UIA tree — if `find_control` reports `invokable:false`/not-found, the control genuinely needs a **foregrounded** `desktop_click`. So: prefer `desktop_ui_click` (background) → fall back to `desktop_click` (foreground) only when UIA can't reach it.
+
+#### Near-complete UIA surface (v1.9.0+) — enumerate, read, drive, with a foreground-hint contract
+
+v1.9.0 expands UIA from ~3 patterns to a near-complete agent-drivable client. **Every UIA verb now returns a `foreground` block** so you know — *before and after* — whether a call steals the user's screen:
+
+```
+"foreground": { "predicted": "background|fallback-possible|foreground",  // from the static class + the resolved path, BEFORE acting
+                "observed":  "background|foreground|n/a",                 // MEASURED (GetForegroundWindow before/after); reads = n/a
+                "raised":    true|false,                                  // did THIS call bring a window to front?
+                "pathTaken": "uia-pattern|sendinput-fallback|setfocus|read-only",
+                "reason":    "<short>" }
+```
+
+**Shared selector on every verb:** `{hwnd|window(titleContains)}` + `{name|contains|automationId|role}` + `scope:"window"(default)|"popups"|"subtree:<automationId>"` + `nth:<int>` (0-based — target the Nth match without the exact name). Prefer `automationId` (stable, locale-independent). Rects are screen px with `centerX/centerY`; `space:"image"+shotId` is accepted wherever a coordinate is taken.
+
+- **Enumeration (read-only, ungated):**
+  - `desktop_ui_tree {window|hwnd, maxDepth?, roleFilter?[], nameContains?, maxNodes?(500), scope?}` — **flagship.** Dump the a11y subtree; nodes carry rect + invokable/settable + value/toggleState/expandState/selected/rangeValue + `children[]`. Honors Chromium's lazy tree (wake-retry); `truncated:true` when it hits `maxNodes` (logged, never silent).
+  - `desktop_ui_from_point {x,y | space:"image",shotId,x,y}` — the control under a pixel.
+  - `desktop_find_controls {selector, maxResults?(25)}` — ALL matches as an array with `nth` indices (vs `find_control`'s single best).
+- **Reading (read-only, ungated):** `desktop_ui_text {selector, range?:"all"|"selection"|"visible"}` (TextPattern); `desktop_ui_get {selector}` (current value/toggle/range/selection/expand state); `desktop_ui_grid_get {selector, row?, col?}` (GridPattern cell + rowCount/columnCount).
+- **Actions (gated by shell-auto-approve; background-first via the pattern, SendInput-click fallback only when the pattern is absent → then `raised:true`):** `desktop_ui_toggle {selector, state?}`, `desktop_ui_expand {selector, action?:expand|collapse|toggle}`, `desktop_ui_select {selector, action?:select|add|remove}`, `desktop_ui_scroll {selector, dir?, amount?}`, `desktop_ui_set_range {selector, value}`, `desktop_ui_focus {selector}` (**bg:foreground** — usually raises; reports it), `desktop_ui_window {window, action:minimize|maximize|restore|close|move|resize}`.
+- **Events (v1.9.3 — REACT instead of poll; read-only, ungated):**
+  - `desktop_ui_watch {event, window?|hwnd?, properties?}` → `{watchId}`. `event` ∈ `focus` (desktop-wide "what got focus") | `window-opened`/`window-closed` (new/closed top-level windows — these three can be global) | `invoke` | `selection` | `text-changed` | `text-selection` | `menu-opened` | `tooltip-opened` | `notification` | `live-region` | `structure` | `property` (these REQUIRE a `window`, else `errorCode:window_required` — avoids a desktop firehose). Cap 16 watches.
+  - `desktop_ui_events {sinceSeq?, watchId?, max?}` → DRAIN the buffer (poll cursor; there is NO server-push over the relay). Returns `{events:[{seq, watchId, event, ts, element:{name,role,automationId,rect,hwnd}, eventType|property|changeType}], nextSeq, highestSeq, missedEvents, activeWatches}`. Poll with `sinceSeq=nextSeq`. Events ALSO appear in the ab GUI activity-log. The 500-deep ring is shared across all watches; `missedEvents:true` = you polled too slowly.
+  - `desktop_ui_unwatch {watchId|"all"}` → stop. **Canonical use:** waiting on an OTP/confirm dialog → `ui_watch {event:"window-opened"}`, poll `ui_events` until the window appears, then act on it (no busy screenshot loop).
+- **Introspection:** `desktop_ui_capabilities {}` — **read-only, ungated.** The foreground-hint TABLE per verb (`staticClass` + measured `{win32, chromium-pattern, chromium-fallback}`). **Consult it BEFORE a call to know if it'll steal the screen, without acting.** `desktop_ui_selftest {confirm?, window?}` writes/refreshes it (empirically measures when `confirm:true`).
+
+**Integrity boundary:** an elevated/admin window or the UAC secure desktop returns `errorCode:"uia_integrity_blocked"` (never a silent no-op) — a normal-integrity bridge cannot drive a higher-integrity process.
+
+#### Zero-math coordinate clicks — `coordMap` + image-space (v1.8.175+)
+
+You no longer recompute scale/offset/DPI to click what you see in a screenshot. Every screenshot verb returns a **`coordMap`**:
+
+```jsonc
+"coordMap": {
+  "shotId": "shot-w5050328-1",
+  "image": { "w": 1372, "h": 1031 },              // the DELIVERED (safe) PNG's pixels
+  "screenRect": { "x": 594, "y": 254, "w": 1372, "h": 1031 },  // physical px = input-verb space
+  "dpiScale": 1.5,
+  "imageToScreen": { "sx": 1.0, "sy": 1.0, "ox": 594, "oy": 254 }  // screen = img*s + o
+}
+```
+
+Two ways to use it:
+- **Let ab convert (preferred, zero math):** `desktop_click {space:"image", shotId, x, y}` where `x,y` are pixels in that screenshot. Also works on `desktop_double_click`/`right_click`/`hover`. The `shotId` comes from the capture's `coordMap.shotId` (last ~64 shots retained; re-capture if it expires).
+- **Compute yourself:** `screenX = x*sx + ox`, `screenY = y*sy + oy`.
+
+`screenRect` is in the SAME physical-px space as `desktop_list_windows` rects and the `desktop_click` default (`space:"screen"`).
+
+> **Driving a GUI app that pops error boxes / modal dialogs? Read the dedicated [`adom-bridge-window-capture`](WINDOW_CAPTURE.md) skill.** `desktop_screenshot_window {hwnd}` captures ONE window AND the child dialogs / error boxes it owns, even when the window is backgrounded/occluded/minimized (PrintWindow, no focus steal). It is the breakthrough for automating native apps whose dialogs a full-screen grab can't see. The rest of this section is the reference; that skill is the how-and-why.
+
+**Popups (owned):** As of **v1.8.177**, `desktop_screenshot_window` **also captures the window's OWNED popups** — borderless confirm bubbles (Chromium's "Remove '\<ext\>'?"), owned dropdowns, owned dialogs — that don't enumerate in `desktop_list_windows` and aren't visible in a PrintWindow of the main window. They ride back as a top-level **`screenshots[]`** array (the same generic shape `kicad_screenshot_all` uses; the CLI auto-pulls each entry's `fullPath`→`localPath` and `safePath`→`localSafePath`). `ownedPopupCount` is always present (0 = none). Each entry carries `hwnd`, `title`, `kind:"owned_popup"`, and its own `coordMap`+`shotId`, so you can **click the bubble's buttons** with `{space:"image", shotId, x, y}` or drive them in the background by name via `desktop_ui_click {scope:"popups"}`. This is the generic mechanism — there's no app-specific "Chrome bubble" verb; every window screenshot surfaces any owned popups so you get the data and decide. **Use `desktop_screenshot_screen`** (full virtual-screen grab) only for popups *not owned* by your target window, or to see everything at once.
+
+**Screen geometry on every shot (v1.8.178):** every `desktop_screenshot_window` / `_screen` response now carries:
+- **`windowRect: {x,y,w,h,monitor}`** — the window's position + size on the overall (possibly multi-monitor) desktop, in physical screen px. Each owned popup entry in `screenshots[]` gets its own **`rect: {x,y,w,h,monitor}`** too — so you know where every captured surface sits, not just its pixels.
+- **`display: {virtualScreen, primary{w,h,dpi,scale}, monitors[], monitorOfWindow}`** — the full monitor topology: total virtual bounds, and per-monitor `bounds`/`dpi`/`scale`/`primary`. `monitorOfWindow` indexes into `monitors[]`. (Same data as the standalone `desktop_display` verb, folded in.)
+- **`drive: "background"`** — screenshots never foreground the window (PrintWindow/WGC). The companion `_related` field lists sibling screenshot/window verbs.
+
+**Screenshot cache is self-cleaning + self-describing (v1.9.107/108/113):** the CLI auto-pulls every screenshot to ONE user-visible, namespaced dir on the caller's machine (`~/project/screenshots/adom-bridge/`, else `~/.adom/screenshots/`; `ADOM_SHOTS_DIR` overrides) — never `/tmp` anymore. Shots are **bucketed by kind into subfolders**: `window/` (a specific window / app / owned popup) and `screen/` (a full-desktop grab). **Human-readable filenames (v1.9.113):** `<YYYY-MM-DDThh-mm-ss.mmm>[-<hwnd>].png` — a sortable ISO stamp (lexicographic == chronological), plus the `hwnd` for a window capture; the `window`/`screen` kind is NOT repeated in the name because the folder already says it. **One file when small (v1.9.114):** if the shot was already within the safe size cap (the common case) it's a single `<stem>.png` and `localFullPath == localSafePath` — no redundant re-encoded copy. Only a shot large enough to be downscaled produces a `<stem>.full.png` + `<stem>.safe.png` pair (Read the `.safe` one for image analysis; use `.full` for archive). Each shot gets a **`<stem>.json` sidecar** (shotlog-style: `source`, `timestamp`, `kind`, dims + `bytes`, `coordMap`, `rect`; a full+safe pair shares one). **Parent/child grouping (v1.9.111/113):** when `desktop_screenshot_window` returns owned popups in `screenshots[]`, the parent AND each pulled child share the same stem, and each child gets a **`.popup-NN` label** — e.g. parent `2026-07-15T01-14-16.937-986710.safe.png` and children `2026-07-15T01-14-16.937-986710.popup-01.safe.png`, `...popup-02...`. So a plain `ls` shows the whole capture grouped (shared stem) and the role (`.popup-NN`) without opening a sidecar; the sidecar also carries `parent` + `popupIndex`. (`kicad_screenshot_all` returns sibling windows with no parent, so those keep their own names.) A janitor prunes it (7 days / 2 GB / newest kept; sidecars follow their PNG, orphans swept) and drains the old `/tmp/ad-shots` + `/tmp/adom-bridge-screenshots` backlogs, running opportunistically at most once/24h on any CLI call. **You do not need to clean it up or write your own cron.** Every screenshot response carries a `_cacheHint`; verify coverage with **`adom-bridge janitor`** (status: each subfolder, size, policy, last sweep) or force a sweep with **`adom-bridge janitor '{"sub":"run"}'`**. It never touches other tools' files under `~/project/screenshots/` (e.g. shotlog). Tune via `ADOM_SHOTS_MAX_AGE_DAYS` / `ADOM_SHOTS_MAX_GB` / `ADOM_SHOTS_MAX_FILES`, or disable with `ADOM_JANITOR=0`.
+
+**Background vs foreground driving (v1.8.178):** every desktop driving verb carries a structured **`drive`** field (`"background"` | `"foreground"` | `"n/a"`) — in `GET /commands`, in `adom-bridge help <verb>`, and echoed in the verb's own response. **Background** (no foreground / focus steal / cursor move — UIA + capture): `desktop_ui_click`, `desktop_ui_set`, `desktop_navigate`, `desktop_find_control`, `desktop_screenshot_window/_screen`, `desktop_record_window_start`. **Foreground** (SendInput → goes to the focused window, so ab foregrounds first): `desktop_click`/`_double_click`/`_right_click`/`_hover`, `desktop_type`, `desktop_press_key`, `desktop_bring_to_front`. Run **`adom-bridge help background`** for the full grouping. Rule: to act without disturbing the user's window, drive by NAME (`desktop_find_control` → `desktop_ui_click`/`ui_set`); fall back to coordinate clicks/keys only when the control isn't in the UIA tree.
+
+**Click a control by name → coords:** `desktop_find_control` returns `best.rect{x,y,w,h,centerX,centerY}` in screen px — `desktop_click {x:centerX, y:centerY}` to SendInput-click it (handy when `invokable`/`settable` are both false). Target by `name`, `contains`, `role`, or `automationId` (stable, locale-independent).
+
+**Keyboard chords:** `desktop_press_key` accepts a chord as one string `["ctrl+w"]` OR separate tokens `["ctrl","w"]` — both mean Ctrl held + W. A *sequence* of distinct chords uses `+` per element: `["ctrl+l","enter"]`. The reply echoes `chords` showing how ab interpreted your `keys`.
+
+- `desktop_flash_window` (v1.8.152+) -- Flash an **arbitrary** window's taskbar button orange (Win32 `FlashWindowEx`) as an "attention / ongoing activity" cue. Resolve the HWND with `desktop_list_windows` first. Args: `hwnd` (int) OR `titleContains` (string); `mode` (`"until_focused"` default — flashes until the user clicks the window; or `"count"`); `count` (int, `mode:"count"` only, default 3); `stop` (bool — clear an active flash). Returns `{ok, hwnd, title, mode}`. **Lightweight by design** (direct FlashWindowEx, no process spawn) so a bridge can call it after every verb. Distinct from the puppeteer bridge's `pup_alert_window`, which only flashes pup's OWN tracked windows — this flashes any window on the host. For progress + overlay-icon status, use `desktop_taskbar`.
+  - Example: `adom-bridge desktop_flash_window '{"hwnd":133560}'` then `adom-bridge desktop_flash_window '{"hwnd":133560,"stop":true}'` to clear.
+- `desktop_taskbar` (v1.8.152+) -- Paint **glanceable status** on any window's taskbar button via `ITaskbarList3` (progress bar + overlay icon) + `FlashWindowEx`, so a bridge can show what the AI is doing on the **real app window it drives** (e.g. native-browser putting an "Adom is driving" badge + task progress on the Chrome/Edge button). Works on windows owned by **other processes**. Persistent COM (init once, reuse) — safe to tick progress frequently; no process spawn. Resolve the HWND via `desktop_list_windows`. Args (all channels optional; provide ≥1):
+  - `hwnd` (int) OR `titleContains` (string)
+  - `flash`: `"until_focused"` | `"stop"`
+  - `progress`: `{state: "normal"|"paused"|"error"|"indeterminate"|"none", value?: 0..100}` — **state→color**: normal=green, **paused=yellow** (use for human-in-the-loop gates: captcha / 2FA / login), error=red, indeterminate=marquee, none=clear.
+  - `overlay`: `{badge: "adom"|"none", icon?: "<PNG or .ico — file path OR base64>", tooltip?: "<hover>", avatar?, profileDir?, userDataDir?, composite?}` — built-in badges are `adom` (the Adom logo — a "driven by Adom" trust tell) and `none` (clear); 3rd-party bridges pass their **own** `icon` (a **PNG** or `.ico`, file path or base64 — ab magic-sniffs + renders at 32px). ab stays generic: it paints whatever art you hand it. `tooltip` is the overlay's accessible description.
+    - **Compositing onto a Chrome/Edge profile avatar (v1.9.110, #154):** Windows gives ONE overlay slot per taskbar button, and Chrome/Edge use it for the **profile avatar** — so a bare `badge:"adom"` would EVICT the profile face (you'd lose "work vs personal"). To keep the avatar AND show "Adom is driving", pass the avatar and ab composites the mark onto it (bottom-right ~47%): `overlay:{badge:"adom", avatar:"<PNG path or base64>"}`, or name the profile with `overlay:{badge:"adom", profileDir:"Profile 1", userDataDir?:"<User Data root>"}` (ab reads `<UserData>/<profileDir>/Google Profile Picture.png`; `userDataDir` is derived from the window's exe if omitted). `composite:false` opts out (raw mark). If the avatar can't be resolved ab falls back to the plain mark — never errors. The CALLER (which knows its profile — e.g. the browser extension) supplies the avatar; ab does not reverse-engineer it (one browser process serves all profiles, so the process command line has no `--profile-directory`).
+  - `thumbnailTooltip` (v1.9.153): the taskbar **hover-preview tooltip** (`ITaskbarList3::SetThumbnailTooltip`). The ONLY uncapped text surface on the preview — the window title truncates ~25-30 chars, this string does not (and takes newlines). e.g. `"Adom Pup / Adom wiki / LOGGED-IN view / Chrome for Testing / 3 tabs"`. Pass `""` to clear it back to the title. Works on a window ab does not own.
+  - `thumbnailClip` (v1.9.153): crop the live hover preview to a client-space region — `{x,y,w,h}`, or `null` to reset to the whole window (`SetThumbnailClip`).
+  - Returns `{ok, hwnd, title, applied:[...]}`. Clears: `flash:"stop"`, `progress.state:"none"`, `overlay.badge:"none"`, `thumbnailTooltip:""`, `thumbnailClip:null` — call these on task-end / window-close to clean up.
+  - Example (long task, human gate, then done):
+    ```bash
+    adom-bridge desktop_taskbar '{"hwnd":133560,"overlay":{"badge":"adom","tooltip":"Adom is driving this browser"},"progress":{"state":"indeterminate"}}'
+    adom-bridge desktop_taskbar '{"hwnd":133560,"progress":{"state":"paused"},"flash":"until_focused"}'   # captcha — come look
+    adom-bridge desktop_taskbar '{"hwnd":133560,"progress":{"state":"none"},"overlay":{"badge":"none"},"flash":"stop"}'  # done — clear all
+    ```
+- `desktop_set_window_identity` + `desktop_register_app_identity` (v1.9.134+) -- **Full window-identity takeover.** Make a window you drive present itself as YOUR app: the taskbar button, Alt-Tab entry, hover tooltip and any user pin read your name and icon instead of the process that happens to own the HWND. Built for a bridge driving a borrowed host app (a Chrome for Testing window otherwise reads "Test" with Chrome's icon, which is two brands and a confusing word). ab is generic here — it applies whatever `appId` / `iconPath` / `displayName` you pass and knows nothing about which app that is.
+
+  **You need BOTH halves.** `set_window_identity` stamps a LIVE window (`PKEY_AppUserModel_ID` + `WM_SETICON`); `register_app_identity` teaches Windows what that `appId` MEANS (an HKCU `AppUserModelId` key + a Start Menu shortcut carrying the same AUMID). An unregistered appId falls back to the owning exe's icon, so half one alone leaves Alt-Tab wrong.
+
+    ```bash
+    # Once per install. Ship the .ico in your bridge's release zip; pass its cache path.
+    # `target`/`args` are what a user's PINNED tile launches — point it at a real verb so
+    # the pin opens a managed window instead of an orphan app.
+    adom-bridge desktop_register_app_identity '{"appId":"Adom.Pup","displayName":"Adom Pup",
+      "iconPath":"C:/.../adom-pup.ico",
+      "args":"pup_open_window {\"sessionId\":\"pinned\",\"owner\":\"pinned-launch\"}"}'
+
+    # Per window, e.g. at park time. cacheKey survives page-title churn.
+    adom-bridge desktop_set_window_identity '{"cacheKey":"<sessionId>",
+      "titleContains":"(session: <sessionId>)","appId":"Adom.Pup",
+      "displayName":"Adom Pup","iconPath":"C:/.../adom-pup.ico"}'
+    ```
+  - Window target: `hwnd` OR `titleContains` OR `cacheKey` (+ `fresh` to re-resolve). Response carries `resolvedBy` (`hwnd` | `cachedHwnd` | `title`) and `applied[]`.
+  - **Identity is per-HWND and dies with the window** — re-apply after a window is recreated.
+  - ab holds the icon handles for its whole process lifetime. Icon handles are process-owned: a transient setter leaves windows pointing at dead handles, so the icon reverts moments later. ab being long-lived is exactly why it owns them.
+  - `register_app_identity` writes HKCU only (never a UAC prompt). It is gated for RELAY callers like `write_file`; a bridge calling over the loopback API is trusted by transport and ungated.
+  - **Jump-list tasks (v1.9.139+): `desktop_set_window_jumplist {appId, tasks}`** puts YOUR actions on the taskbar right-click menu of every window stamped with that appId. Jump lists attach to the AUMID, so per-session appIds give each window its OWN menu. Each task: `{title (required), target? (exe, defaults to ab's bundled CLI — so `args` can simply be an ab/bridge verb + JSON), args?, iconPath?, description?}`. Tasks launch minimized (no console flash). Max 16; `tasks:[]` clears (call at session close, alongside `unregister_app_identity`). Re-set anytime to update the menu. Tier-2 gated for relay callers; loopback bridges ungated.
+  - **Per-session / transient appIds (v1.9.136+): register REGISTRY-ONLY with `shortcut:false`, unregister on close.** If you stamp per-session AUMIDs (e.g. `Adom.Pup.<sessionId>` so each window keeps its own taskbar button in split mode), an UNREGISTERED AUMID makes Alt-Tab fall back to the owning exe's icon. `desktop_register_app_identity {appId, displayName, iconPath, shortcut:false}` writes just the HKCU AppUserModelId key (DisplayName + IconUri) — Alt-Tab and taskbar hover resolve the name + icon with NO Start Menu entry. Pair with `desktop_unregister_app_identity {appId}` at session close (idempotent; removes the key plus any shortcut carrying that AUMID; ab's own `inc.adom.bridge` identity is protected). Keep ONE shortcut-mode registration as the pinnable launcher. **Known cost (wiki #155, measured): without a visible Start Menu shortcut carrying the AUMID the shell resolves it lazily on the first right-click, so the jump list flashes and only the second click stays.** `anchor:true` (opt-in, default off since 2.1.49) writes a small visible anchor `.lnk` inside one Start Menu subfolder (`anchorFolder`, default "Adom Bridge"; pass it on unregister too) that fixes it, but it is a real Start Menu entry (All apps, "Recently added", search), and a hidden `.lnk`, `NoStartPage` or `SHAddToRecentDocs` do not anchor. John's default: a clean Start Menu.
+  - **`desktop_set_window_jumplist`** (v1.9.139+) adds the right-click menu on the taskbar button (per-AUMID; `tasks:[]` clears) and, with `hwnd`+`headerIcon`, brands the header row (the app tile above Pin/Close).
+  - **Icon format — read the `iconCheck` these verbs return (v1.9.152).** `desktop_set_window_identity` / `desktop_register_app_identity` / `desktop_set_window_jumplist` return an `iconCheck {kind,sizes,issues,ok,hint}` (or `headerIconCheck`) that magic-sniffs the file and explains why an icon would render as a generic white document: a **256px `.ico` size not PNG-compressed** (the Vista+ trap), **SVG** (the Win32 shell can't load it), a `.ico` with no small size, an `.exe` where an image is wanted. If `iconCheck.ok` is false, fix the file and re-stamp. Ship a multi-size `.ico` (16/24/32/48/256, the 256 PNG-compressed). **Full guide:** the `adom-bridge-window-identity` skill (AUMID model, the register+stamp two-halves rule, jump-list header, taskbar overlay + thumbnail, the live-tile trap, a recipe).
+- `desktop_revoke_approvals` -- Revoke all shell auto-approve permissions and deny pending approvals. The next shell command will show the approval dialog.
+  - Example: `adom-bridge desktop_revoke_approvals`
+- `desktop_demo_panel` -- Floaty glass BACK / PLAY-PAUSE / NEXT / MUTE transport for a guided demo the USER paces (v2.1.0+, mute/callback v2.1.17+). `show` puts it up (reason required; same-id shows persist omitted fields so a stage advance never un-pauses), `poll` between beats drains the user's presses (honor paused / next / back / mute / stop; `muted` rides every reply -- silence your narration audio while it is true), `hide` when the show ends. A LOCAL caller (ah thread, bridge) may pass `eventCallbackUrl` (loopback http) to get every press POSTed instantly; remote callers pace with poll alone. A press never executes anything -- it only queues an event for you. **The full demo recipe (panel + captions + cursor, stop design, the pacing loop) is the `adom-bridge-demo-kit` skill -- read it before building a demo.**
+- `desktop_caption` -- Show a global caption overlay that stays visible above ALL windows (KiCad, Fusion, Chrome). Native Win32 overlay — not a browser DOM element. Click-through: mouse events pass to windows below. Captured by screen recordings (browser `getDisplayMedia`, OBS, Game Bar).
+  - Show: `adom-bridge desktop_caption '{"text":"Step 1: Opening the board","position":"top","size":"large","duration":3000}'`
+  - Custom position: `adom-bridge desktop_caption '{"text":"Look here","x":0.3,"y":0.2,"size":"large","persist":true}'`
+  - Hide: `adom-bridge desktop_caption '{"action":"hide"}'`
+  - **Every caption carries a close box (X) and, when you gave a `reason`, a line naming your thread.** Both are the user's protection: the X is their only way to dismiss a caption without an AI, and the attribution answers "which of my ~20 threads is drawing on my screen".
+  - **`clean:true` removes BOTH, and it is deliberately hard to get — treat it as rare.** It exists for one case: the user is recording a demo video and explicitly asked for a caption with no chrome. It requires `userAsked:true` AND a `cleanReason` (>=30 chars) saying what they asked for, it is **refused outright** with `persist:true`, and its duration is capped at **2 minutes** (re-issue the same id to extend while you are supervising).
+  - **Do not set `clean:true` because the caption looks better without the X.** The user cannot dismiss a clean caption at all, so if it lands over something they need, their only recourse is to find the AI that put it there. If you cannot point to the user asking for a chrome-free caption, the answer is no. A normal caption looks the same in a recording apart from a small X.
+  - List what's on screen (v1.9.217): `adom-bridge desktop_caption '{"action":"list"}'` — returns `{captions:[{id,ageMs,expiresInMs,persist,overdue}]}`; the authoritative check (caption overlays do NOT appear in `desktop_list_windows`). TTLs are fail-safe: a 15s reaper closes any caption that outlives its deadline. Do not keep a caption alive with a same-id refresh loop as a nag — the user experiences one endless caption.
+  - Multiple simultaneous captions (use `id` to keep them independent):
+    ```
+    adom-bridge desktop_caption '{"text":"Step 1: Opening board","id":"step","position":"center","size":"large","persist":true}'
+    adom-bridge desktop_caption '{"text":"REC ●","id":"status","position":"bottom-left","size":"medium","persist":true}'
+    ```
+  - Replace only the step caption (status stays):
+    ```
+    adom-bridge desktop_caption '{"text":"Step 2: Routing","id":"step","position":"center","size":"large","persist":true}'
+    ```
+  - Hide just the step caption: `adom-bridge desktop_caption '{"action":"hide","id":"step"}'`
+  - Args:
+    - `text` (string) — caption text
+    - `id` (string, optional) — identifies this caption. Captions with the same id replace each other; different ids coexist simultaneously. Default `"_default"` — so bare calls without id still replace each other for backward compat.
+    - `position` — preset: `"top"`, `"bottom"` (default), `"center"`, `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-right"`
+    - `x` (float 0.0–1.0) — normalized screen X, overrides position horizontal. 0.0 = left edge, 1.0 = right edge. Centers the caption box on this point.
+    - `y` (float 0.0–1.0) — normalized screen Y, overrides position vertical. 0.0 = top edge, 1.0 = bottom edge.
+    - `size` — preset: `"large"` (72px), `"medium"` (32px, default), `"small"` (20px)
+    - `fontSize` (int) — custom font size in px (8–400). Overrides `size` preset when provided.
+    - `duration` (ms) — auto-dismiss timer. **Omitted or `0` → `30000` (30s); clamped to max `600000` (10 min).** Captions ALWAYS auto-expire (v1.8.138+) so a forgotten one can't be stranded on the user's desktop. To keep one up longer, **re-issue the same `id`** (resets the timer) or pass a bigger `duration`.
+    - `persist` (bool, optional) — `true` = sticky, NO auto-dismiss. Supervised use only (e.g. demo recordings); you MUST then dismiss it yourself with `action:"hide"`. This is the only way to a never-expiring caption (`duration:0` no longer does that).
+    - `action` — `"hide"` to dismiss a caption (with `id`: hides only that caption; without `id`: hides all captions), `"force-clear"` to EnumWindows and destroy ALL caption windows regardless of id (nuclear option — use at top of demo scripts for guaranteed clean slate)
+  - Captions with the same `id` replace each other instantly (previous destroyed, no fade overlap). Captions with different ids coexist — multiple captions can be visible simultaneously.
+
+### Desktop Screenshots
+
+Take screenshots of the user's desktop or individual windows. All screenshots use lossless PNG.
+
+**Always save screenshots** to `project-content/screenshots/`.
+
+**Naming convention:** `desktop-<descriptive-name>-YYYY-MM-DD-HhMMam/pm.png`
+
+**Workflow:** Call `desktop_list_windows` first to get HWNDs, then `desktop_screenshot_window` with the HWND.
+
+- `desktop_list_windows` -- List all visible windows (returns HWND, title, class name, position/size, and `z` = Z-order index, 0 = topmost)
+- `desktop_find_window` (v1.8.153+) -- Resolve a window's HWND by `titleContains` and/or `className` (case-insensitive substrings), returned in Z-order with `best` = the topmost match. Use this instead of diffing `desktop_list_windows` before/after launching something — it's race-free for "the window I just opened." Returns `{ok, count, best:{hwnd,title,className,z,rect}|null, windows[]}` (`ok` true only when ≥1 matched). Pass `best.hwnd` to `desktop_taskbar` / `desktop_flash_window` / `desktop_screenshot_window`.
+  - Example: `adom-bridge desktop_find_window '{"className":"Chrome_WidgetWin_1","titleContains":"GitHub"}'`
+- `desktop_activity_filter` (v1.8.155+) -- Scope the **user's GUI activity log** so they watch the slice you care about while you work (e.g. focus it on one bridge before a debugging session). Args: `bridge` (a bridge registry name from `bridge_list` | `"none"` = only global/non-bridge ab commands | `"all"`/omit = everything), `text` (free-text substring, ANDs with bridge), `clear` (bool — reset). **Drives the human's GUI view only — it does NOT change which verbs you can call or what they return.** The GUI shows a status bar stating exactly what's shown + what's hidden.
+  - Example: `adom-bridge desktop_activity_filter '{"bridge":"kicad"}'` then `adom-bridge desktop_activity_filter '{"clear":true}'`
+- `desktop_screenshot_window` -- Capture a specific window by HWND
+- `desktop_screenshot_screen` -- Capture the entire desktop (all monitors)
+- `desktop_ad_scroll` (v1.9.86+) -- **Scroll ab's OWN window panels.** ab is a fully AI-controllable app, so you can drive its own scrollbars — most usefully to page the **bridges sidebar** and screenshot cards that are below the fold. Args: `panel` (`bridges` default | `activity` | `connections`), `to` (`top`|`bottom`, absolute — wins over `dy`), `dy` (relative px, default 400; negative = up). Returns `{ok, panel, scrolled, state:{scrollTop,scrollHeight,clientHeight,atTop,atBottom,found}|null, _hint}` — round-tripped from the live window so you can **loop until `state.atBottom==true`**. A collapsed bridges sidebar is auto-expanded first; `state==null` means the panel didn't report (collapsed/empty).
+  - Capture-all-cards workflow: `desktop_ad_scroll '{"panel":"bridges","to":"top"}'` → `desktop_screenshot_window` (ab hwnd) → `desktop_ad_scroll '{"panel":"bridges"}'` → screenshot → repeat until `atBottom`.
+
+### App self-update (relay-driven, v1.9.87+)
+
+ab auto-updates itself from the wiki manifest, but historically only a HUMAN clicking the footer "Install now" banner could apply it — so a headless / RDP / fleet box (a fresh Azure VM) could sit a version behind with no path forward from the relay. These verbs give the AI that path (same shape as the shell-approval surfacing verbs). Use `--target <box>`.
+
+- `update_status` (read-only, ungated) -- `{currentVersion, latestVersion, updateAvailable, updateReady, state, busy, updateMode}`. `updateReady:true` = the newer version is downloaded + SHA-verified on disk, appliable with no network.
+- `update_check` -- force a manifest check now; if newer, download + verify (stage) it in the background. Poll `update_status` until `updateReady:true`.
+- `apply_update` -- the programmatic "Install now": apply the staged update + relaunch ab. Respects `busy` (refuses if a command is in flight). Only ever applies ab's own downloaded + SHA-verified SIGNED wiki release. Returns `{applying:true}` then ab restarts (the relay drops + reconnects; poll `targets`/`ping` for the new version). If not staged yet, it kicks staging and tells you to poll + retry.
+- `request_update_approval` -- surface the "Update available — Install now / Later" banner on the target + bring ab to the front (for an ATTENDED box where the human should decide). Does NOT apply; `apply_update` installs.
+- `update_set_mode {mode: auto|prompt|off}` -- the auto-apply POLICY. `auto` = unattended stage+apply on the 4h/on-launch poll (set this ONCE on headless fleet boxes and they self-update every release with no relay call); `prompt` = show the banner (default, attended); `off` = no checks.
+  - Fleet flow: `update_status --target <box>` → if `updateAvailable` and unattended, `apply_update --target <box>` (or set `update_set_mode {"mode":"auto"}` once). A box must already be on ≥1.9.87 to have these verbs; the one-time bootstrap of an older box still needs a human click OR `auto` mode.
+
+### Hydrogen companion mode (v1.9.218+)
+
+When a HUMAN opens ab on a machine where Hydrogen is detected (embedded marker, Hydrogen's ports.json, or a discoverable Hydrogen install), ab shows an identity overlay ("This is Adom Bridge" + a large Open Hydrogen button), instantly opens or foregrounds Hydrogen, and places its own window directly below Hydrogen's in z-order — most people who open ab by hand were looking for Hydrogen. Facts an AI should know:
+
+- Human-open detection = bare argv AND parent process `explorer.exe` (double-click, Start menu, search, pins). Machine launches — `--autostart` boot, Hydrogen `--embedded` respawns, the relauncher/`restart` verb, CLI-style invocations — NEVER trigger it, so a remote `restart` cannot bounce the user's screen.
+- One-shot placement: ab does not fight the user's later alt-tabbing, and it is NOT a real Win32 child window (ab's lifecycle stays independent — the recovery-channel contract holds; if Hydrogen cannot be launched the overlay says so and ab stays fully usable).
+- Toggle: Settings > Hydrogen > "Act as a companion to Hydrogen", or `settings_set {"settings":{"hd_child_mode":false}}`. Default ON (self-gates on Hydrogen detection, so standalone installs never see it).
+- Forensics: every decision slogs `ah-COMPANION:` lines to startup.log.
+
+### User settings over the API (`settings_get` / `settings_set`, v1.9.214+)
+
+ab's Settings-panel preferences are readable and settable over the API. This is the sanctioned channel for an embedding app (Hydrogen) to render ab's settings in its own panel and forward the user's changes; it also lets a fleet operator read or fix a box's boot/update prefs remotely.
+
+```bash
+adom-bridge settings_get
+adom-bridge settings_set '{"settings": {"launch_on_boot": true, "update_mode": "auto"}}'
+```
+
+- Settable keys (whitelist): `launch_on_boot`, `always_show_window_on_launch`, `update_mode` (auto|prompt|off), `auto_restart_for_updates`, `update_idle_minutes` (1..1440), `prewarm_runtimes`, `prewarm_cft` (auto|always|never), `file_receive_directory`. Anything else lands in `rejected` — servers, shell approval (grants are human-only), and blocked peers have their own surfaces and are deliberately not settable here.
+- `launch_on_boot` changes apply the OS Startup artifact immediately; `settings_get` also returns `autostartArtifactPresent` so you can see intent-vs-artifact drift.
+- `settings_set` is Tier-2 gated for relay (cloud-AI) callers — carry a `reason` and expect the human-approval flow, like `shell_execute`. Local/loopback callers (Hydrogen, bridges, the local CLI) are trusted by transport.
+- Self-heal: ab re-verifies the launch-on-boot artifact every ~60s while running (not just at launch), so anything that deletes the Startup shortcut behind ab's back gets healed within a minute — with a `RECONCILE:` forensic line in `startup.log`.
+
+### Browser automation (`pup_*`, Puppeteer/pup) — bridge-owned; light pointer
+
+The pup bridge is **cloud-owned** and ships its OWN full skill (its wiki page / skill pkg — `bridge_list` names it; `adom-bridge sync_skills` installs it). This page keeps only the pointer plus first-touch examples; sessions/profiles, credential vault, downloads, recording, CDP details are the bridge's skill.
+
+Most-used verbs:
+
+```bash
+adom-bridge pup_open_window '{"sessionId": "s1", "profile": "p1", "url": "https://example.com"}'
+adom-bridge pup_navigate '{"sessionId": "s1", "url": "https://example.com/page2"}'
+adom-bridge pup_screenshot '{"sessionId": "s1"}'
+adom-bridge pup_eval '{"sessionId": "s1", "expression": "document.title"}'
+adom-bridge pup_fetch_url '{"url": "https://example.com/data.json"}'
+```
+
+`pup_readiness` is the read-only probe (never spawns or downloads). Full details: the bridge's own skill via `sync_skills`.
+
+### Screen recording — ab's desktop recorder (tab recording is pup's)
+
+ab owns DESKTOP recording: a visible HUD opens with the REASON you supply, so the user always sees that recording is on and why. Full guide: the `adom-bridge-recording` skill.
+
+```bash
+adom-bridge desktop_recorder_open '{"reason": "record the DRC walkthrough for review"}'
+adom-bridge desktop_record_start '{"confirmDesktopNotTabRecording": true}'
+# ... drive the desktop ...
+adom-bridge desktop_record_stop '{}'
+adom-bridge desktop_record_list '{}'
+adom-bridge desktop_recorder_close '{}'
+```
+
+`desktop_record_start` without `confirmDesktopNotTabRecording: true` refuses with `errorCode: desktop_record_needs_confirmation` — that guard exists because recording a BROWSER TAB is the pup bridge's separate feature (`pup_record_start` etc., see pup's own skill).
+
+### Filesystem primitives — `desktop_list_files` / `desktop_watch_files` / `desktop_pull_glob` (v1.5.0+)
+
+**These are the canonical "wait for a download" primitives.** They replace the `shell_execute` + PowerShell-poll-Downloads pattern that earlier callers (chip-fetcher, similar tools) had to use. No shell, no user approval prompt, no parsing of `dir` output. They run pure Rust on the desktop side, so they're fast, predictable, and never trip over PowerShell quoting.
+
+The pattern they replace looks like this:
+
+```powershell
+# OLD — DON'T do this for new code:
+$before = (Get-Date).ToFileTime()
+# … click download …
+while (-not (Get-ChildItem ~/Downloads -Filter ul_*.zip | Where { $_.LastWriteTime.ToFileTime() -gt $before })) {
+  Start-Sleep -Seconds 1
+}
+$file = Get-ChildItem ~/Downloads -Filter ul_*.zip | Sort LastWriteTime -Desc | Select -First 1
+```
+
+becomes one call:
+
+```bash
+# NEW — single primitive, no shell:
+adom-bridge desktop_watch_files '{
+  "path": "%USERPROFILE%\\Downloads",
+  "glob": "ul_*.zip",
+  "timeoutMs": 60000
+}'
+# → {ok:true, file:{path,name,size,mtime}, elapsedMs} on success
+# → {ok:false, error:"timeout", elapsedMs, _hint, ...} on timeout
+```
+
+#### `desktop_list_files` — one-shot directory listing
+
+Lists files in a directory (non-recursive) matching a shell-glob, optionally filtered to those modified after a given timestamp.
+
+- Args: `path` (Windows abs path; `~` / `%USERPROFILE%` / `%APPDATA%` / `%LOCALAPPDATA%` / `%TEMP%` are expanded), `glob` (default `*`; shell-style with `*` and `?`; case-insensitive on Windows), `modifiedSince` (optional unix-seconds OR ISO-8601 string).
+- Returns: `{ok, path, glob, files: [{path, name, size, mtime}, ...] sorted newest-first, count}`.
+- Does NOT recurse. Lists one directory only.
+
+#### `desktop_watch_files` — block until a match arrives
+
+Polls the directory every `pollMs` (default 1000) until at least one file matches the glob with `mtime > since`, or `timeoutMs` (default 60000, max 600000 = 10 min) elapses.
+
+- Args: same as `desktop_list_files` plus `since` (defaults to **now** — without an explicit value, only NEW files report), `timeoutMs`, `pollMs`.
+- Returns on match: `{ok:true, file:{path,name,size,mtime}, elapsedMs}`.
+- Returns on timeout: `{ok:false, error:"timeout", elapsedMs, _hint, path, glob}`.
+- The `since`-defaults-to-now behavior matches the canonical "click then watch" flow. If you might miss the file by starting the watch slightly late (e.g. fast small downloads), record `$(date +%s)` BEFORE the click and pass it as `since`.
+
+#### `desktop_pull_glob` — one-shot orchestrator (recommended for download flows)
+
+Composes `desktop_list_files` (or `desktop_watch_files` if `wait:true`) with the existing streaming `pull_file` mechanism. The whole "wait for a download then pull it" flow in one call:
+
+```bash
+BEFORE=$(date +%s)
+# … trigger the download click via pup_input_dispatch …
+adom-bridge desktop_pull_glob "{
+  \"path\": \"%USERPROFILE%\\\\Downloads\",
+  \"glob\": \"ul_*.zip\",
+  \"since\": $BEFORE,
+  \"wait\": true,
+  \"timeoutMs\": 60000,
+  \"saveTo\": \"/tmp/cse-out\"
+}"
+# → {ok:true, files:[{name,path,size,sha256,chunks}, ...], errors:[], matchedCount}
+```
+
+- When `wait:true`: blocks via `desktop_watch_files` until at least one match appears, then re-lists the directory and pulls **everything matching** (so a `.crdownload` + final `.zip` written in the same poll tick both come along).
+- When `wait:false` (default): just lists what's there now and pulls those.
+- Pulls use the existing `pull_file` streaming pipeline — sha256-verified, ~1MB chunks, resumes the same way `pull_file` does.
+
+#### Glob semantics
+
+- `*` matches any run of non-separator chars (within a single filename — these primitives don't recurse).
+- `?` matches a single non-separator char.
+- Case-insensitive on Windows (matches the filesystem); case-sensitive on macOS/Linux.
+- Examples: `ul_*.zip`, `LIB_*.zip`, `*.pdf`, `datasheet_*.pdf`, `*.step`, `*.STEP` (same on Windows).
+
+#### Path expansion
+
+- `~` and `~/foo` → home dir (Linux/macOS convention; works on Windows too).
+- `%USERPROFILE%` → home dir (Windows; also works cross-platform).
+- `%APPDATA%` → Windows roaming app data (`dirs::config_dir()` on others).
+- `%LOCALAPPDATA%` → Windows local app data (`dirs::data_local_dir()` on others).
+- `%TEMP%` → Windows TEMP env var; `/tmp` on Linux/macOS.
+- Expansion is case-insensitive: `%userprofile%` works the same as `%USERPROFILE%`.
+- Forward slashes (`/`) and back slashes (`\`) both work in the path string.
+
+#### Time format for `since` / `modifiedSince`
+
+- Number: unix seconds (e.g. `1746483600`). Floats accepted.
+- String of digits: same (e.g. `"1746483600"`).
+- ISO-8601 / RFC-3339 string: e.g. `"2026-05-04T22:30:00Z"` or with offset `"2026-05-04T15:30:00-07:00"`.
+- Files with `mtime <= since` are filtered out (strict `>`).
+
+### Hydrogen (`hd_*`) — proxy + build/lifecycle for the sibling Tauri app
+
+When the user has **Hydrogen** running (a sibling Tauri v2 app at `C:\Github\hydrogen-desktop`), built-in `hd_*` verbs reach into it. NOT a separate bridge process — adom-bridge proxies HTTP calls directly to Hydrogen's control API.
+
+**Port discovery (v1.8.72+):** Hydrogen's control API lives on **port `47084`** (default; the actual port is read from `%APPDATA%\hydrogen-desktop\ports.json` key `control` on every `hd_api` call, fallback 47084). Pre-v1.8.72 the verbs were hardcoded to Hydrogen's legacy `:9001` webview-eval port, which Hydrogen doesn't bind anymore — that's why `hd_status` reporting "Hydrogen not running" while Hydrogen's window is visible is the upgrade signal.
+
+#### The canonical generic verb — `hd_api` (v1.8.72+)
+
+```bash
+adom-bridge hd_api '{"method":"GET","path":"/health"}'
+adom-bridge hd_api '{"method":"POST","path":"/setup/run-step","body":{"id":"welcome"}}'
+adom-bridge hd_api '{"method":"GET","path":"/wsl/status"}'
+```
+
+Generic HTTP pass-through to any Hydrogen endpoint. Raw JSON in `body` — no curl-through-the-relay quote mangling. Returns `{success, status, body, port, method, path}` mirroring Hydrogen's response. If Hydrogen isn't running, returns `{ok:false, error:"Hydrogen not reachable on :47084", _hint:"..."}` instead of timing out.
+
+**Public denylist** — these paths are refused with `{ok:false, error:"not_allowed_in_public", denylist_match:"..."}` on public ab builds (use the internal `hd-dev` cargo feature to bypass):
+
+```
+/wsl/unregister, /setup/virgin-reset, /container/destroy,
+/container/reset, /workspace/reset, /workspace/destroy
+```
+
+#### Inspect + drive a running Hydrogen (v1.8.15+, post-v1.8.72 rework)
+
+| Verb | What | Status |
+|---|---|---|
+| `hd_status` | Composes ab-side facts (running, repo SHA) + Hydrogen's `/workspace/health` + `/buildinfo` relayed | ✓ shipped |
+| `hd_api` | Generic HTTP pass-through (above) | ✓ v1.8.72+ |
+| `hd_log '{"tail":30}'` | Tail `%APPDATA%\hydrogen-desktop\hydrogen-desktop.log` (reads disk — works EVEN when Hydrogen is down) | ✓ shipped |
+| `hd_open_url '{"url":"...","browser":"chrome","profileDir":"Default"}'` | POST `/open-in-profile` — open URL in a specific browser profile | ✓ shipped |
+| `hd_browser_profiles` | GET `/browser-profiles` — enumerate browsers + profiles | ✓ shipped |
+| `hd_screenshot` / `hd_shot` | Find Hydrogen window, capture lossless PNG via PrintWindow; `hd_shot` adds region-scoped variant | ✓ shipped |
+| `hd_eval '{"js":"..."}'` | POST `/eval` — run JS in Hydrogen's main webview | ⚠ **Moved to `hd-dev` in v1.8.72.** Public returns `verb_moved_to_hd_dev`. Use `hd_api '{"method":"POST","path":"/eval","body":{"js":"..."}}'` |
+| `hd_iframe_eval '{"js":"...","contextIndex":0}'` | POST `/iframe-eval` — JS in code-server iframe via CDP | ⚠ Moved to `hd-dev`. Use `hd_api` equivalent |
+| `hd_reload_vscode` | POST `/reload-vscode` | ⚠ Moved to `hd-dev`. Use `hd_api` equivalent |
+| `hd_container_exec '{"command":"..."}'` | POST `/container-exec` | ⚠ Moved to `hd-dev`. Use `hd_api` equivalent |
+| `hd_launch` / `hd_stop` / `hd_restart` | Hydrogen process lifecycle | ✓ shipped |
+| `hd_ship` | Atomic build+relaunch+verify-SHA (see below) | ✓ shipped |
+| `hd_build*` (v1.8.16+) | Build pipeline orchestration | ⚠ Moved to `hd-dev` in v1.8.72 (Hydrogen developers only) |
+
+#### Atomic ship — `hd_ship` (v1.8.49+) — START HERE for post-push rebuilds
+
+**One verb, one call, one structured pass/fail.** Replaces the 4-step chain `hd_stop` → `hd_build_rust` → poll `hd_build_status` → `hd_launch` → `curl :47084/buildinfo`. Eliminates the "is the new code actually running?" guesswork after every push.
+
+Sequence inside one call:
+1. taskkill Hydrogen + poll until zero instances (frees the exe lock)
+2. `git fetch && git reset --hard origin/main && rev-parse HEAD` — asserts `HEAD == expectSha` (fails fast if GitHub hasn't replicated the push yet)
+3. if `clean:true`, `cargo clean -p hydrogen-desktop` (defeats stale-relink)
+4. `cargo build` and parse stderr for `Compiling hydrogen-desktop` to know whether anything actually compiled
+5. launch + poll `http://127.0.0.1:47084/buildinfo` until it responds + assert `build_sha == expectSha`
+
+```bash
+# End-to-end after a push:
+git push && SHA=$(git rev-parse HEAD) && \
+  adom-bridge hd_ship "{\"expectSha\":\"$SHA\"}"
+```
+
+Args:
+- `expectSha` — **REQUIRED** string. Full or prefix SHA of the commit you want running. Bidirectional-prefix match (`abc123` matches the full SHA starting with `abc123` and vice versa).
+- `clean` — optional bool, default `false`. `true` forces `cargo clean -p hydrogen-desktop` before build. Use when a prior `hd_ship` succeeded but `runningSha != expectSha` (the stale-relink trap — cargo said `Finished` but reused the cached binary).
+
+Returns on success: `{ok:true, builtSha (== expectSha), runningSha (== expectSha), compiled:bool, elapsedSecs, _hint}`. `compiled:false` on success means cargo found nothing to recompile (cached relink or HEAD didn't actually change — usually fine but surface to caller in case the push was a no-op).
+
+Returns on failure: `{ok:false, failedAt:'args'|'kill'|'git'|'clean'|'build'|'launch'|'verify', error, builtSha (set after git step), runningSha (set if launch worked but verify saw the wrong SHA), compiled (set after build step), elapsedSecs, _hint}`. The partials let you reason about WHERE it broke:
+
+| `failedAt` | What it means |
+|---|---|
+| `args` | `expectSha` missing / malformed |
+| `kill` | Couldn't taskkill Hydrogen (rare — usually permissions) |
+| `git` | `git fetch / reset` failed, OR `HEAD != expectSha` after reset (push hasn't replicated to origin/main yet — retry in a few seconds) |
+| `clean` | `cargo clean` failed (rare) |
+| `build` | `cargo build` failed — read `_hint` for next step (usually `hd_build_log` to see the compile error) |
+| `launch` | Cargo finished but `hydrogen-desktop.exe` wouldn't start — `binary_missing` or process spawn error |
+| `verify` | Hydrogen launched but `/buildinfo` either never responded or reported a different SHA than `expectSha` (the stale-relink trap — retry with `clean:true`) |
+
+Long-running: cold cargo build can take 2-3 min. CLI WS timeout is 12 min — call as a single sync invocation and wait. Don't poll inside `hd_ship`; it does its own internal polling.
+
+#### Lower-level build + lifecycle suite (v1.8.16+, enriched in v1.8.52+)
+
+Use these directly only when you need finer control than `hd_ship` provides (e.g. frontend-only build, watching log stream live, manual launch sequencing). For the common "I pushed code, get it running" path use `hd_ship`.
+
+The relay's `shell_execute` has a 30s timeout; Hydrogen's `pnpm build` + `cargo build` exceed that, so the build is split into async-spawn verbs + sync poll/tail verbs:
+
+```bash
+# Frontend-only rebuild, watch progress, relaunch (no hd_ship since hd_ship is Rust-build-only)
+adom-bridge hd_stop
+adom-bridge hd_build_frontend '{"show":false}'      # returns {ok, pid, logPath} immediately
+OFFSET=0
+while true; do
+  RESP=$(adom-bridge hd_build_tail "{\"offset\":$OFFSET}")
+  echo "$RESP" | jq -r '.lines[]'
+  DONE=$(echo "$RESP" | jq -r '.done')
+  OFFSET=$(echo "$RESP" | jq -r '.newOffset')
+  [[ "$DONE" == "true" ]] && break
+  sleep 3
+done
+adom-bridge hd_build_status      # confirm succeeded:true && relinkOnly:false
+adom-bridge hd_launch            # start the new debug binary
+```
+
+##### `hd_build` / `hd_build_frontend` / `hd_build_rust` — async-spawn build verbs
+
+| Verb | What |
+|---|---|
+| `hd_build '{"show":false}'` | Full async build: `git pull` + `pnpm build` + `cargo build`. Returns instantly with `{pid, logPath, flavor:'full'}`. Final log line is `BUILD_OK` or `BUILD_FAILED: <step>`. |
+| `hd_build_frontend` | Just `pnpm build` (root). Returns `{pid, logPath, flavor:'frontend'}`. |
+| `hd_build_rust` | Just `cargo build` (src-tauri/). **v1.8.52+:** dispatch response also carries `builtSha` + `exeMtimeBefore` + `exeSizeBefore` (captured at spawn time into `%TEMP%\hd-build-meta.json`) so the subsequent `hd_build_status` / `hd_launch` don't need a separate `git rev-parse` + `stat` call. Returns `{ok, pid, logPath, flavor:'rust', show, lingerSecs, builtSha, exeMtimeBefore, exeSizeBefore, _hint}`. |
+
+##### `hd_build_status` — sync state probe (v1.8.52+ enriched)
+
+Returns:
+```
+{
+  ok, building, succeeded, failed,
+  lastLines:[string],                  # last ~40 lines of stderr
+  logPath, pid, pidAlive,
+  failureReason,                       # 'compile_error' | 'exe_locked' | 'orphaned_no_sentinel'
+  compiledCrates:[string],             # names parsed from 'Compiling X v...' lines
+  relinkOnly:bool,                     # true iff succeeded && compiledCrates is empty
+  exeChanged:bool,                     # mtime OR size after differs from before
+  exeMtimeBefore:int, exeMtimeAfter:int,   # unix seconds
+  exeSizeBefore:int,  exeSizeAfter:int,    # bytes
+  exeLocked:bool,                      # true when build failed because hydrogen-desktop.exe was held
+  holderPids:[int],                    # PIDs holding the exe — taskkill these
+  builtSha:string|null,                # SHA hd_build_rust/hd_build was dispatched at
+  elapsedSecs:int,
+  flavor:string,                       # 'rust' | 'frontend' | 'full'
+  _hint
+}
+```
+
+**`relinkOnly:true` on success is the silent-fail trap to look for** — your push didn't actually rebuild because cargo found nothing to recompile. Usually means your source changes weren't pulled, or you touched a file the workspace doesn't track. Use `hd_ship` with `clean:true` to force a fresh build.
+
+**`exeLocked:true` on failure** + `holderPids` tells you exactly which PIDs to taskkill before retry; or just use `hd_ship` which kills Hydrogen before building.
+
+##### `hd_launch` — start the debug binary (v1.8.52+ enriched)
+
+Args: `killExisting` — optional bool, default `false`. When `false` and Hydrogen is already running, refuses with `reason:'already_running'` so you don't accidentally attach to a stale process. When `true`, taskkill the existing instance with a 600 ms grace period before launching fresh.
+
+Returns on launch: `{ok:true, launched:true, wasAlreadyRunning:bool, killedFirst:bool, pid:int (Hydrogen's actual PID, not the cmd-wrapper), exePath, builtSha:string|null, _hint}`.
+
+Returns on refusal: `{ok:false, launched:false, wasAlreadyRunning:bool, pid:int|null, killedFirst:false, reason, _hint}`. `reason` ∈:
+- `build_in_progress` — wait for `hd_build_status.building:false`
+- `build_failed` — fix and retry `hd_build` (or use `hd_ship`)
+- `already_running` — pass `killExisting:true` to force-kill+relaunch, or use `hd_restart`
+- `binary_missing` — `target/debug/hydrogen-desktop.exe` not on disk; run `hd_build_rust` (or `hd_ship`) first
+
+**`launched:true, wasAlreadyRunning:false, killedFirst:false` is the proof you need that truly fresh code is running.** Any other combo means you should compare `builtSha` to Hydrogen's actual `/buildinfo.build_sha`.
+
+##### `hd_stop` / `hd_restart` / `hd_build_log` / `hd_build_tail`
+
+| Verb | What |
+|---|---|
+| `hd_stop` | `taskkill /F /IM hydrogen-desktop.exe`. `{wasRunning}` distinguishes killed vs no-op. |
+| `hd_restart` | Stop + launch in one call. Same guards as `hd_launch` (skip `already_running`). |
+| `hd_build_log` | Full log dump from `%TEMP%\hd-build.log`. |
+| `hd_build_tail '{"offset":N}'` | Incremental stream — `{lines, newOffset, totalBytes, done, succeeded, _hint}`. Pass `newOffset` back for the next chunk. |
+
+The `show: true` arg on any build verb opens a visible PowerShell console window so the user can watch the build scroll. Default `show: false` runs hidden.
+
+**Auto-close (v1.8.23+).** Visible build windows auto-close 30 seconds after the final `BUILD_OK` / `BUILD_FAILED` line — long enough for the user to read the last error, short enough that build-after-build sessions don't accumulate orphan windows. The window prints a clear green/red "auto-closes in 30 seconds" banner before sleeping. Override with `lingerSecs`:
+- `'{"show":true, "lingerSecs":60}'` — give yourself 60s instead of 30
+- `'{"show":true, "lingerSecs":0}'` — close immediately, no grace period
+- `'{"show":true, "lingerSecs":3600}'` — keep open for an hour (cap)
+The response includes the applied `lingerSecs` so you can confirm what landed. Hidden builds (`show:false`) ignore `lingerSecs` entirely — no window to linger.
+
+**Don't call `hd_launch` until `hd_build_status` shows `succeeded: true`** — the guard refuses with `reason: "build_failed"` if you do, and the `_hint` tells the AI exactly what to do (`hd_build_log` to see errors, fix, rebuild). Same for `hd_restart`.
+
+#### Named-region screenshots — `hd_shot` (v1.8.54+)
+
+**One verb replaces the `desktop_list_windows | grep 'Hydrogen' → desktop_screenshot_window <hwnd>` chain** (3 calls + fragile HWND parsing). Captures a named region of Hydrogen, produces BOTH a full-res PNG and a Claude-safe-resized copy, and returns rich metadata so the AI never has to chain screenshot → pull → convert → crop → resize → Read manually.
+
+Each shot is **self-identifying**: it includes the running build's SHA + local build time read from Hydrogen's `/buildinfo` so you can confirm you're looking at the build you expect before trusting what you see (no more "this screenshot was from the previous binary, not my fix" confusion).
+
+Regions are deterministic — they resolve via Hydrogen window bounds + CDP element rects queried through Hydrogen's `/eval` endpoint. No AI-supplied pixel coords.
+
+Args:
+- `region` — **REQUIRED**. One of:
+  - `full` — whole Hydrogen window
+  - `titlebar` — top ~40 px strip (Hydrogen's build SHA / timestamp readout lives here)
+  - `vscode` — VS Code iframe pane via CDP element rect
+  - `setup-panel` — Setup Steps panel (`.setup-panel` / `.setup-panel-output`)
+  - `wiki` — wiki / browser tab pane
+  - `claude` — Claude Code panel
+- `resizeMax` — optional int, default `1400`. Longest side of the safe-resized copy. Use ≈800 to fit more shots in one Claude turn; 1568 for max fidelity.
+
+Returns:
+```
+{
+  ok, region,
+  fullPath,                    # lossless raw PNG — for shotlog/archival, NOT Read
+  safePath,                    # ≤resizeMax PNG — pull_file this, Read this
+  fullSize:[w,h], safeSize:[w,h],
+  clipRect:[x,y,w,h],          # captured-image pixels (NOT screen pixels)
+  capturedAtLocal,
+  runningBuildSha,             # from Hydrogen's /buildinfo — null if Hydrogen doesn't expose it yet
+  runningBuildLocal,
+  hdWindowFound:bool, regionFound:bool,
+  windowOuter:[w,h], capturedSize:[w,h],
+  _hints: {
+    pull,                      # exact pull_file command for safePath
+    fullForArchive,            # note that fullPath is for archive, not Read
+    staleWindow,               # set when runningBuildSha looks wrong
+    regionMiss                 # set when regionFound:false
+  }
+}
+```
+
+Recipe — verify-which-build-is-running + confirm-config-change-took-effect + full dump:
+
+```bash
+# After hd_ship, confirm the titlebar shows the SHA you expect:
+adom-bridge hd_shot '{"region":"titlebar"}'
+# → runningBuildSha lets you assert this before trusting any other shot
+
+# After flipping a Setup Steps toggle, screenshot the panel to confirm:
+adom-bridge hd_shot '{"region":"setup-panel","resizeMax":1568}'
+
+# Full-window dump for general debugging:
+adom-bridge hd_shot '{"region":"full"}'
+```
+
+Edge cases:
+- **Unknown region** — refusal: `{ok:false, error, knownRegions:[...]}`. No fallback — fix the call.
+- **`regionFound:false`** — the element rect wasn't in Hydrogen's DOM. The panel/iframe may not be mounted yet, OR Hydrogen's markup changed and `region_selectors()` in `hd_bridge.rs` is out of date. The shot is **still produced** (falls back to the full window) so you have something to look at; check `_hints.regionMiss` for the reason.
+- **`runningBuildSha:null`** — Hydrogen's `/buildinfo` isn't exposed yet on the running version. The shot is still produced; you just can't self-verify which build it represents.
+
+**Always pull_file the `safePath` and Read THAT** — it's already sized for Claude's image analysis. The `fullPath` is for shotlog / disk archival, NOT direct Read (may exceed Claude's per-image budget). The `_hints.pull` field gives you the exact `pull_file` command to copy-paste.
+
+**Old workaround to drop:** Do NOT use `desktop_list_windows | filter 'Hydrogen' | desktop_screenshot_window <hwnd>` anymore for Hydrogen — `hd_shot` replaces that entire pattern. Generic `desktop_screenshot_window` still applies to non-ah windows (other apps, dialogs, etc.).
+
+### TCP Port-forward Tunnels — `tunnel open|close|list|check|rdp` + `display` (v1.8.85+, reworked v1.8.147)
+
+Reach a TCP service addressable only from the **cloud side** through the **laptop side**: ab binds a `127.0.0.1:<port>` listener on the laptop and pumps bytes over the existing ab↔relay WebSocket; the relay dials the upstream `to`. First use case: RDP into a Windows VM behind an NSG only the cloud container reaches — mstsc on the laptop connects to a local port and is talking through the cloud. Same path works for SSH, VNC, HTTP, postgres — any TCP.
+
+**`tunnel` is a grouped verb** (`rdp` / `tunnel_close` / `tunnel_list` remain back-compat aliases):
+
+```bash
+# Open a VERIFIED tunnel (both legs probed before ok). Auto-picks a free local port.
+adom-bridge --target <name> tunnel open '{"to":"127.0.0.1:13389"}'
+
+# RDP: open + verify + launch mstsc, sized to the laptop's real screen.
+adom-bridge --target <name> tunnel rdp '{"to":"127.0.0.1:13389","size":"90%"}'
+#   size: "90%" (default) | "100%" | "fullscreen" | "maximized"
+#   OR monitor:<index> (0=primary)  OR explicit width+height
+
+adom-bridge --target <name> tunnel list           # live tunnels + leak detection
+adom-bridge --target <name> tunnel check '{"tunnelId":<id>}'   # per-leg health
+adom-bridge --target <name> tunnel close '{"tunnelId":<id>}'   # or {"all":true}
+
+adom-bridge --target <name> display               # monitor geometry (for sizing)
+```
+
+**`--target` is mandatory when >1 ab is connected.** v1.8.147 fixed a false-success bug: the bind, the upstream probe, and the mstsc launch now ALL resolve to the SAME machine. (Before, the bind could land on one ab and mstsc launch on another → "port bound" on the VM, "nothing listening" on the laptop, a bogus `ok:true`.) No target + multiple ABs → `ambiguous_target` listing the names; `--target all` is rejected (a tunnel binds one machine). `adom-bridge targets` lists connected ABs.
+
+**Active health verification — every `open`/`rdp`/`check` PROVES the path before reporting `ok`:**
+- **local-bind** — ab self-probes `127.0.0.1:<boundPort>` right after binding. If it can't connect, ab tears the tunnel down and returns `ok:false` (this alone kills the false-success class).
+- **upstream-refused** — the relay dials `to` (retry/backoff ~4×/2.5s). If unreachable, the tunnel is torn down (no leaked row) and `ok:false`.
+- A failure names the leg: `failedLeg: "relay-to-ad" | "local-bind" | "upstream-refused"`. Health fields surfaced: `listening`, `relayConnected`, `upstreamReachable`, `connCount`, `mstscAlive`.
+
+**Progressive hints.** Every response carries `_hint` (what's true now) + `_next` (the exact next verb with real values, copy-pasteable). e.g. a successful open's `_next` hands you the `tunnel rdp` / `tunnel check` / `tunnel close` commands with the real `to`/`target`/`tunnelId` filled in. A missing `to` returns a structured error with an example. Walk the workflow from the responses alone.
+
+**Display-aware RDP sizing.** `tunnel rdp` resolves `size`/`monitor`/`width`/`height` against the laptop's real screen (queried via `display` — `EnumDisplayMonitors` + per-monitor DPI), writes an `.rdp` file with the geometry, and launches mstsc. e.g. `size:"90%"` on a 2560×1600 primary → a 2304×1440 window. Default 90% of primary. You never hardcode a resolution — call `display` if you want the layout first.
+
+**`tunnel list` reconciles + reaps leaks.** It cross-checks the relay registry against every connected ab's own registry and reports `leaks:[...]` for rows only one side knows about; `tunnel close '{"all":true}'` reaps them. The relay stores the actually-bound `localPort` (so `tunnel close '{"local":<port>}'` works).
+
+Architectural notes for Claude:
+- Bytes-only — no payload parsing, so any TCP service works. TLS/cert-pinning still pins to whatever the cloud-side dial resolves (for RDP the upstream cert CN must match what mstsc expects).
+- Each fresh laptop-side TCP connection gets its own connId multiplexed over one tunnelId; concurrent mstsc reconnects / parallel sessions work without re-opening. Backpressure bounded (256-slot mpsc/conn, 64 KiB buf).
+- Tunnels don't survive ab/relay restarts. If mstsc disconnects, `tunnel check` (names the dead leg), then re-open.
+- The classic RDP collision (Windows' own RDP owns `0.0.0.0:3389`) is dodged by `rdp`'s default `local:13389` + `SO_EXCLUSIVEADDRUSE` + ephemeral fallback (`fellBack:true` in the response; read `localPort` for the real port).
+
+**Old workarounds to drop**: (1) NSG WAN-IP whitelisting for roaming-laptop RDP — the tunnel rides existing auth, reachable regardless of WAN IP. (2) Trusting a bare `ok:true` from the old `rdp` — it could be a dead port; now `ok` means both legs were probed. (3) Hardcoding mstsc resolution — pass `size`/`monitor`; ab resolves against the real screen.
+
+### Shell — `shell_execute` (escape hatch only)
+
+- `shell_execute` -- Run a shell command on the desktop. The CLI handles approval polling internally — it returns the final `{success, output, error, exitCode}` once the user clicks Allow on the desktop dialog. **You do not need to poll, retry, or call `get_deferred_result` yourself.** The CLI emits `HINT:` lines to stderr while waiting (every 15s) so an AI Monitor sees progress.
+- `shell_kill_all` -- Kill all running shell commands and deny pending approvals.
+
+**v1.7.16 fix.** Earlier versions (v1.7.15 specifically) had a regression where the CLI's approval-wait loop re-sent the command every 1s instead of polling for the deferred result; that produced an infinite "Another shell command is already waiting for approval" loop because each retry created a fresh approval the user could never out-click. v1.7.16 fixes it. If you see that error string with a `>= 1.7.16` CLI, the bug is back — file an issue. If you see it with `< 1.7.16`, upgrade the CLI: `adom-wiki asset get apps/adom-bridge docker_binary -o /usr/local/bin/adom-bridge`.
+
+**Deprecated for download polling.** As of v1.5.0, use `desktop_watch_files` / `desktop_pull_glob` for waiting on download arrivals — those don't require user approval, don't go through PowerShell quoting, and are O(directory entries) rather than spawning a process every second. `shell_execute` itself stays as an escape hatch for genuinely shell-only operations (multi-step ad-hoc admin tasks, chained pipelines, etc.).
+
+Use `where python` / `C:\Python3xx\python.exe` for Python -- avoid `python` which may not be on PATH.
+
+#### `run_script` + `wsl_exec` — base64-payload script runners (v1.8.46+)
+
+When you want to send a multi-line script to the desktop without the shell-quoting hell that `shell_execute` requires, use these two verbs. The script crosses the wire as base64 so NO escaping survives to be mangled by cmd.exe, PowerShell parser quirks, MSYS path conversion, or wsl.exe's `--` / nested-quote / `$_` rules. The caller never hand-escapes anything.
+
+Both verbs require shell auto-approve to be active — same trust level as `shell_execute`. They refuse cleanly with an actionable error if not approved; no per-call modal (these are programmatic verbs).
+
+**Reading the result — `status` + `durationMs` (v1.8.162+).** EVERY CLI result now carries a single authoritative **`status`** field so you never have to guess whether an empty `stdout` was a real empty-output success or a timeout:
+
+| `status` | meaning | what to do |
+|---|---|---|
+| `ok` | completed (stdout may legitimately be empty) | use `exitCode`/`stdout`/`stderr` |
+| `timeout` | did NOT finish in time (NOT an empty success) | raise `timeoutSeconds`, or use a detached job (below) |
+| `busy` | desktop couldn't service it (WSL wedged / no client connected) | check `adom-bridge status`; `wsl_recover` for WSL; retry |
+| `error` | the command/verb failed | read `error` / `stderr` / `_hint` |
+
+`durationMs` is the wall-clock of the call. `exitCode`/`stdout`/`stderr` pass through unchanged; on `timeout` the verb's `partialStdout`/`partialStderr` hold what was written before the kill. A `timeout`/`busy` result also carries a recovery `_hint`. **For multi-minute work don't fight the timeout** — use a detached job that returns instantly + polls: `wsl_exec_async` / `wsl_import` / `wsl_export` → poll `wsl_job_status` (or `launch_process` for a general long-running command). This is the cure for the "1.4 GB import EOFs the sync call" problem.
+
+**`run_script`** — base64 script + interpreter (cmd / powershell / bash):
+
+```bash
+SCRIPT_B64=$(python3 -c "import base64; print(base64.b64encode(b'''
+echo \"multi-line script\"
+VAR=\"value with spaces and \$dollars\"
+echo \"VAR=\$VAR\"
+exit 0
+''').decode())")
+adom-bridge run_script "{\"interpreter\":\"bash\",\"scriptB64\":\"$SCRIPT_B64\"}"
+# → {success, ok, stdout, stderr, exitCode}
+```
+
+Args: `interpreter` (`cmd` | `powershell` | `bash`), `scriptB64` (required), `timeoutSeconds` (default 60).
+
+PowerShell prefers `pwsh` (PS 7+) if on PATH, falls back to `powershell.exe` (5.1).
+
+- **`bash` runs via WSL2, NOT Git Bash.** The Windows host's first `bash` on PATH is `wsl.exe -d <default-distro> bash` (verified at `C:\Windows\System32\bash.exe`). The script is piped to bash's stdin (no temp file, no path-form mismatch — no MSYS `/S` → `S:/` corruption, no nested-quote loss). The decoded script bytes are written to bash's stdin and stdin is closed; bash reads + executes without ever opening a file. For explicit distro / user control, use `wsl_exec`.
+
+**`wsl_exec`** — base64 script + distro + user, executed via the canonical `wsl -d <distro> -u <user> -- bash -lc <decoded>` argv array:
+
+```bash
+SCRIPT_B64=$(python3 -c "import base64; print(base64.b64encode(b'''
+cd /mnt/c/Github/adom-bridge
+git status --short | head -10
+exit 0
+''').decode())")
+adom-bridge wsl_exec "{\"distro\":\"Ubuntu\",\"user\":\"root\",\"scriptB64\":\"$SCRIPT_B64\"}"
+# → {success, ok, stdout, stderr, exitCode}
+```
+
+Args: `distro` (e.g. `Ubuntu`, `Adom-Workspace`), `user` (e.g. `adom`, `root`), `scriptB64`, `timeoutSeconds` (default 60).
+
+Why argv (not shell string): Rust's `std::process::Command` on Windows applies proper `CommandLineToArgvW` quoting per argv element. `wsl.exe` sees `bash -lc <decoded>` as three distinct argv items even when the decoded script contains quotes, `$`, backslashes, newlines, pipes — anything. `bash`'s `-c` then sees the entire script as ONE string with no outer-shell interpretation.
+
+Output decoding: `wsl.exe` defaults to UTF-16LE when invoked from the Windows console subsystem. Both verbs auto-detect (BOM check + odd-position-NULL heuristic) and decode to UTF-8. Output is never wrapped in another shell that might re-interpret it.
+
+Pitfalls these verbs eliminate:
+- `cmd.exe`'s `&`, `|`, `^`, `%var%` interpretation
+- PowerShell's parser quirks around nested quotes + `$` interpolation
+- Git Bash MSYS converting `/S` → `S:/` etc.
+- WSL's `--` parser limits + nested-quote loss
+- UTF-16LE corruption on wsl.exe output
+
+#### WSL wedge defense — `wsl_wedged` + `wsl_recover` (v1.8.157+)
+
+Every `wsl_exec` / `run_script bash` spawns a `wsl.exe` client. If WSL's service (`LxssManager`) wedges — common after a laptop runs for a day, or under heavy parallel cloud use — those clients block in a wait that `taskkill /F` can't always finish, and retries keep spawning more. Left unchecked they pile up into the hundreds and wedge the whole machine. Three defenses:
+
+1. **Refuse-cap.** When there are already too many `wsl.exe` (`WSL_REFUSE_AT=80`), ab refuses NEW wsl spawns with `errorCode:"wsl_wedged"` instead of adding another doomed client. If you get `wsl_wedged`, don't retry the same command — run `wsl_recover` first.
+2. **`wsl_recover`** — reap orphaned/hung `wsl.exe`, **DRY-RUN by default** (nothing is killed unless you pass `confirm:true`):
+   ```bash
+   adom-bridge wsl_recover                       # dry-run: lists `candidates` (would-reap) + `spared`
+   adom-bridge wsl_recover '{"confirm":true}'    # reap the candidates
+   adom-bridge wsl_recover '{"confirm":true,"sparePids":[1234]}'   # also protect pid 1234
+   ```
+   It classifies each `wsl.exe`: childless + (0-CPU & old | runaway-CPU) → **candidate**; everything else → **spared**. It **spares any `wsl.exe` with child processes** (that's almost certainly the live distro, e.g. the Hydrogen `Adom-Workspace`), honors `sparePids`, and never touches `wslservice`/`wslhost`/`vmmem`. Review each candidate's `cmd` in the dry-run to confirm the live workspace isn't among them, then confirm. **Never** `wsl --shutdown` (it kills the live workspace too). Reaping childless orphans often cascades — their now-parentless children exit on their own (observed 114 → 18 from reaping 54).
+3. **status wsl block** — `{wslProcessCount, wedged, _hint}` lets you see a pile-up *before* it blocks work. Path differs by transport: **`status.desktop.wsl`** via the CLI/relay (`adom-bridge status` — nested like `desktop.apps`), or top-level **`status.wsl`** on the local direct API (`GET /status`). `wedged:true` at/above `WSL_WARN_AT=50`.
+
+#### Long-running in-distro work + distro lifecycle — golden-image bakes (v1.8.161+)
+
+`wsl_exec` is **synchronous** — it waits for the command and is bounded by the relay's HTTP timeout (~60-120s), so a multi-minute bake (apt, a big download) EOFs. Backgrounding inside the distro (`nohup … &`) doesn't help either: the `wsl.exe` client returns, WSL sees no active session, shuts the distro down, and kills the bg process (wiping `/tmp`). For anything long, use the **async held-session** verbs — ab holds one `wsl.exe` in the foreground for the command's whole lifetime, so the distro stays up:
+
+- **`wsl_exec_async`** → returns a `jobId` + `outputPath` (a live UTF-8 log) immediately; the command runs detached for as long as it takes.
+- **`wsl_job_status {jobId}`** → `{running, exitCode, elapsedMs, outputTail, outputPath}`. Poll until `running:false`; `pull_file` the `outputPath` for the full log. (`wsl_job_list`, `wsl_job_kill {jobId}` round it out.)
+
+```bash
+# golden-image bake: import → run (async) → poll → export → unregister, all via ab
+adom-bridge wsl_import '{"distro":"bake","installDir":"C:/Users/<you>/.adom/wsl/bake","tarball":"C:/.../base.tar"}'
+#   → {jobId}; poll wsl_job_status until done (exitCode 0)
+B64=$(printf 'set -euo pipefail\napt-get update && apt-get install -y build-essential\n' | base64 -w0)
+adom-bridge wsl_exec_async "{\"distro\":\"bake\",\"user\":\"root\",\"scriptB64\":\"$B64\"}"
+adom-bridge wsl_job_status '{"jobId":"wsljob-xxxxxxxx"}'   # repeat until running:false; outputTail = progress
+adom-bridge wsl_export '{"distro":"bake","tarball":"C:/.../golden.tar"}'   # poll, then pull_file the tarball
+adom-bridge wsl_unregister '{"distro":"bake"}'            # cleanup (REFUSES Adom-Workspace)
+adom-bridge wsl_list                                      # {distros:[{name,state,version,default}]}
+```
+
+**systemd user session — `viaRoot`.** On a `systemd=true` distro, `-u <user>` can fail "Failed to start the systemd user session for '<user>'". Pass `"viaRoot": true` to `wsl_exec_async` — ab runs `-u root -- runuser -u <user> -- bash -l`, dropping to the user WITHOUT depending on `[email protected]`.
+
+`wsl_import` / `wsl_export` / `wsl_unregister` are async (jobId + poll) too, so big imports/exports never EOF. All are **strictly scoped to the named distro** — there is no global `wsl --shutdown` path (that would kill the live Hydrogen workspace), and `wsl_unregister` refuses `Adom-Workspace`. Job ids live in ab's memory only (not persisted across an ab restart; the log file survives). The wedge defense above still applies — an over-cap spawn returns `wsl_wedged`.
+
+## Detecting App Installation
+
+After connecting, always run `adom-bridge status` to check what's installed. The `desktop.apps` object tells you exactly what the user has:
+
+```bash
+adom-bridge status
+# Look at the desktop.apps field in the response
+```
+
+### Handling "not installed" errors
+
+When a command returns `errorCode: "node_not_found"`, `errorCode: "kicad_not_installed"`, or `errorCode: "fusion_not_installed"`, guide the user through installation:
+
+**Picking the right native browser + profile (v1.7.1+):**
+
+When you need to open a URL in the user's NATIVE browser AND it matters which account is signed in (work Google Workspace vs personal Gmail vs media YouTube channel etc.), `desktop_open_url` alone isn't enough — you need to target a specific profile. The flow:
+
+```bash
+# 1. Discover what's installed + which profiles are configured.
+adom-bridge desktop_list_browsers '{}'
+# → {
+#     "default": "chrome",
+#     "browsers": [
+#       { "name": "chrome", "displayName": "Google Chrome", "version": "146...",
+#         "exePath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+#         "profiles": [
+#           { "id": "Default",   "name": "Alice (work)", "gaia": "[email protected]",     "isDefault": true },
+#           { "id": "Profile 1", "name": "Personal",     "gaia": "[email protected]" },
+#           { "id": "Profile 2", "name": "Adom Media",   "gaia": "[email protected]" }
+#         ] },
+#       { "name": "edge", "profiles": [...] },
+#       { "name": "firefox", "profiles": [{"id":"default-release","name":"default","isDefault":true}] }
+#     ]
+#   }
+
+# 2. Match the URL's context to the right profile, then open it there.
+# E.g. opening a Google Doc shared by your work team → use the work profile:
+adom-bridge desktop_open_url '{
+  "url":"https://docs.google.com/document/d/...",
+  "browser":"chrome",
+  "profile":"Default"
+}'
+# Or YouTube channel management for the media account:
+adom-bridge desktop_open_url '{
+  "url":"https://studio.youtube.com",
+  "browser":"chrome",
+  "profile":"Profile 2"
+}'
+```
+
+Profile-picking heuristics for Docker Claude:
+- **Workspace / @adom.inc URLs** → match `profile.gaia.endsWith("@adom.inc")` and not the `media@` one → typically `Default`.
+- **Personal Gmail / Drive / etc.** → match `profile.gaia === "[email protected]"` (or whatever the user's personal address resolves to).
+- **YouTube Studio / channel-specific work** → match the media account profile.
+- **Random scratch / experiments** → use the user's Edge profile, where they keep miscellaneous accounts (per the user's stated preference).
+- **No clear match** → fall back to `browser:"default"` (no profile flag) and let the user pick.
+
+`profile` is optional. Omit it to open in whichever profile the browser was last using (legacy v1.6.x behavior). Profile flag is silently ignored when `browser:"default"` (no clean way to inject through the OS URL handler — name the browser explicitly to use it).
+
+### Decrypting the user's saved browser credentials — `desktop_decrypt_browser_credentials` (v1.9.220+)
+
+> **`reason` is REQUIRED here (v2.0.84)** and it is not for the log: the user reads it
+> **on screen**, in a caption above every window, while deciding whether to hand over
+> their saved passwords. Write it for them — say what you are trying to accomplish, not
+> what the command does. Good: `"Signing the adom-you Chrome profile in as you so I can
+> check your orders"`. Weak: `"decrypting credentials"` (that is just the verb again).
+>
+> **What the user sees before anything is decrypted (three surfaces, v2.0.84):**
+> a caption above every window naming **which AI thread** asked, **your reason**, **what
+> it wants** (passwords / cookies) and **from which browsers**, plus a warning that
+> Windows is about to ask for administrator permission; ab's own consent dialog; and a
+> Windows toast carrying the same Continue/Cancel. Any one of them can approve or
+> decline. Expect a visible pause here — a human is reading, and if they were not
+> expecting it they are being told to choose No.
+
+So pup can run an **"adom-you" Chrome profile signed in AS the user** — surfing the web on the user's behalf — it needs the user's real saved logins/cookies to seed that profile. Chrome 127+ encrypts these with **App-Bound Encryption** (the master key is DPAPI-wrapped under the SYSTEM account), so only an elevated helper can decrypt them. This verb is that path.
+
+```bash
+adom-bridge desktop_decrypt_browser_credentials '{
+  "reason": "Signing the adom-you Chrome profile in as you so I can check your orders",
+  "browsers": ["chrome", "edge"],   # optional; default = all installed Chromium browsers
+  "include": ["passwords", "cookies"] # optional; default = both
+}'
+# → { "ok": true,
+#     "passwords": [ { "origin", "username", "password", "sourceBrowser", "sourceProfile", "sourceAccount", "lastUsed" }, ... ],
+#     "cookies":   [ { "host", "name", "value", "path", "sourceBrowser", "sourceProfile", ... }, ... ],
+#     "stats": { "profilesRead", "passwordsOk", "passwordsFailed", "cookiesOk", "cookiesFailed" } }
+```
+
+**How to call it (this is not a normal verb — read this):**
+
+- **LOCAL / bridge callers only.** A relay (cloud-AI) call is refused unconditionally with `errorCode:"relay_forbidden"` and **pops no UAC** — a remote container must never be able to trigger a password-decrypt. pup (a loopback bridge) and the local CLI reach it.
+- **Two human gates, in order:** (1) ab shows an in-window consent dialog + toast naming the requesting caller ("pup is requesting your saved browser passwords/cookies…"); decline → `errorCode:"consent_declined"`. (2) On continue, an elevated signed helper runs behind a **UAC prompt** ("Adom Industries, Inc."); cancel → `errorCode:"elevation_declined"`. The UAC elevation IS the user's permission for the decrypt — by design (John, wiki #457).
+- **Plaintext is returned ONCE over the loopback API and is never written to disk or logged.** Don't echo the values into any other verb's args, any activity-log emit, or any file. Consume the rows, seed the profile/vault, drop them.
+- **errorCodes:** `relay_forbidden` (you called it over the relay — you can't), `consent_declined`, `elevation_declined`, `helper_missing` (the signed helper isn't bundled — the install is broken). Per-item decrypt failures are counted in `stats.*Failed`, never fail the whole run (a managed-profile policy can block cookies; newest-Chrome `v20` blobs are best-effort if Google rotated the elevation-service key).
+- **Pair it with `desktop_list_browsers`** (above) to show the user which browsers/profiles/accounts will be read before you ask.
+
+**Node.js not installed (the puppeteer bridge can't auto-spawn):**
+
+v1.7.0+ — any `pup_*` command returning `errorCode:"node_not_found"` means Node isn't on the desktop machine. Trigger the unattended winget install:
+
+```bash
+adom-bridge desktop_install_node '{}'
+# → runs `winget install --id OpenJS.NodeJS.LTS --silent ...` (Windows only).
+# → ~1-2 min; downloads + installs the Node.js LTS line (well-tested with puppeteer).
+# → returns {ok:true, exitCode:0, _hint:"Retry the original pup_* command"} on success.
+# → on failure: {ok:false, errorCode:"winget_unavailable" | "winget_install_failed", _hint}.
+```
+
+After install, **just retry the original `pup_*` command** — the bridge picks up the new node.exe via the registry App Paths lookup (which winget writes), no Adom Bridge restart needed. v1.7.0+ also pre-fetches Node + Chrome for Testing on first launch after install (background task on AUTOSTART_VERSION 11), so most users will never see `node_not_found` to begin with.
+
+If `desktop_install_node` returns `errorCode:"winget_unavailable"` (older Windows or managed corporate device), fall back to manual:
+
+> Node.js LTS is required for browser automation. winget isn't available on this machine — download Node.js LTS from https://nodejs.org/ and run the installer. Let me know when it's done and I'll retry.
+
+**v1.7.0+ Node detection.** The bridge looks for `node.exe` in:
+- System PATH (via `where node` on Windows, `which node` elsewhere)
+- Windows registry App Paths (catches winget, MSIX, custom-dir installs)
+- Standard install dirs: `C:\Program Files\nodejs\`, `C:\Program Files (x86)\nodejs\`, `%LOCALAPPDATA%\Programs\nodejs\`
+- Per-user version managers: nvm-windows (`%APPDATA%\nvm\`), volta (`%LOCALAPPDATA%\Volta\bin\`), fnm (`%FNM_DIR%`)
+- macOS Homebrew (`/opt/homebrew/bin`, `/usr/local/bin`)
+
+If detection still misses an install on a user's machine, get the actual `node.exe` path from the user — that's a real bug to file.
+
+**KiCad not installed:**
+
+**KiCad not installed:**
+
+v1.6.0+ — try the unattended winget install FIRST before asking the user to download manually:
+
+```bash
+adom-bridge desktop_install_kicad '{}'
+# → runs `winget install --id KiCad.KiCad --silent ...` (Windows only).
+# → 2-5 minutes; downloads ~700 MB then installs.
+# → returns {ok:true, exitCode:0, _hint:"Run kicad_list_versions to verify"} on success.
+# → on failure (no winget / network failure / corporate-managed device):
+#   {ok:false, errorCode:"winget_unavailable" | "winget_install_failed", _hint, ...}
+```
+
+If `desktop_install_kicad` fails with `errorCode:"winget_unavailable"`, fall back to manual:
+
+> KiCad isn't installed and winget isn't available. Download from https://www.kicad.org/download/ — it's free and open source, install the latest stable (9.x or 10.x).
+> Let me know when the install is done and I'll verify the connection.
+
+After EITHER path, have them restart Adom Bridge OR call `kicad_list_versions` again — the kicad bridge caches detection results, so a fresh scan may be needed to pick up freshly-installed binaries.
+
+**v1.6.0+ — improved KiCad detection.** The bridge now scans for KiCad in:
+- `C:\Program Files\KiCad\<version>\` (the standard location)
+- `C:\Program Files (x86)\KiCad\<version>\` (32-bit edge cases)
+- `%LOCALAPPDATA%\Programs\KiCad\<version>\` (winget per-user installs)
+- `%LOCALAPPDATA%\KiCad\<version>\` (rare manual installs)
+- Windows registry: `HKLM\SOFTWARE\KiCad\<version>\InstallationPath` and the `WOW6432Node` mirror
+- `HKCU` mirrors of the above for per-user installs
+- macOS: `/Applications/KiCad/` and `/Applications/` directly
+
+If detection still misses an install on a user's machine, that's a real bug to file — get the actual install path from the user and we'll add it to the scan list.
+
+**Fusion 360 not installed:**
+> Fusion 360 isn't installed on your desktop. Would you like to install it?
+> Download from: https://www.autodesk.com/products/fusion-360
+> It's free for personal/hobby use (requires an Autodesk account).
+> Let me know when the install is done and I'll verify the connection.
+
+After install, have them restart Adom Bridge, then run `adom-bridge status` to verify.
+
+### Handling "not running" errors
+
+When `errorCode: "fusion_not_running"`, launch it programmatically with the first-class startup command:
+```bash
+adom-bridge fusion_start
+# On Windows: discovers exe via %LOCALAPPDATA% env var webdeploy glob.
+# On Docker: delegates to the bridge on the connected desktop via relay.
+# ~15-30s typical. Auto-dismisses startup dialogs.
+# Returns {"addinReady": true, "pickerDismissed": true|false, ...}
+```
+
+KiCad doesn't need to be running for most commands (the bridge launches it on demand).
+
+### Handling "add-in not installed" errors
+
+When Fusion is running but `addinInstalled: false` or `addinConnected: false`:
+> The AdomBridge add-in needs to be installed in Fusion 360. I can install it for you — this lets me control Fusion remotely.
+
+The add-in auto-installs when the Fusion bridge starts and Fusion is detected.
+
+### Handling `fusion_addin_not_responding` errors
+
+When `errorCode: "fusion_addin_not_responding"`, Fusion is running but the AdomBridge add-in isn't answering. Call `fusion_dismiss_blocking_dialogs` FIRST — a modal dialog is the most common cause. If that doesn't help, try `fusion_start` to restart Fusion cleanly. Last resort: user enables add-in manually via UTILITIES > ADD-INS > AdomBridge > Run on Startup + Run.
+
+### Handling `main_thread_busy` errors
+
+When `errorCode: "main_thread_busy"`, the Fusion add-in's main thread is occupied by a long-running command (typically `walk_cloud_tree` or `search_cloud_files`). This applies **across all bridges/sessions** — even if you didn't start the walk, another session might have.
+
+**Do NOT:**
+- Retry the failed command — it will block behind the same lock
+- Call `fusion_dismiss_blocking_dialogs` — there's no dialog to dismiss, and sending Escape will interrupt the active walk
+- Force-kill Fusion — the walk will complete on its own
+
+**Do:**
+- Wait for the walk/search to finish. If you started it, you should be using `adom-bridge watch` (see "Live folder progress streaming with `watch`" above) which streams live progress automatically. If another session started it, poll `fusion_addin_status` every 2–5s to check progress.
+- Use commands that **don't need the main thread** while waiting:
+  - `fusion_addin_status` — check busy state and walk progress
+  - `fusion_window_info` — get window HWND, title, dialogs
+  - `fusion_screenshot_fusion` — capture what Fusion looks like
+  - `fusion_click_fusion` — click in the Fusion window
+  - `fusion_send_key` — send keyboard input
+  - `fusion_close_window` — close a specific dialog by HWND
+
+The response includes progress info:
+```json
+{
+  "errorCode": "main_thread_busy",
+  "busyCommand": "walk_cloud_tree",
+  "elapsedSeconds": 42.3,
+  "walkProgress": {
+    "foldersVisited": 15,
+    "filesFound": 87,
+    "currentFolder": "Molecules/XRP",
+    "queueSize": 8
+  },
+  "_hint": "Add-in is busy with a long-running command. Do NOT retry..."
+}
+```
+
+**Stalled walk detection**: If `fusion_addin_status` returns `busy: true` but `walkProgress` is missing and `mainThreadStalled: true`, a modal dialog is blocking the event loop — the walk was dispatched but never started. Call `fusion_dismiss_blocking_dialogs`, then the walk auto-resumes.
+
+### Auto-recovery (`_autoRecovery` field)
+
+When a fusion_* command fails with "not responding" / "not connected", the CLI automatically:
+1. Calls `fusion_dismiss_blocking_dialogs` to clear any modal
+2. If successful, retries the original command
+3. Attaches `_autoRecovery: {action, dismissed[]}` to the retry result
+
+If you see `_autoRecovery` in a response, the command already succeeded after auto-dismissal — no manual intervention needed. The field is informational.
+
+## Troubleshooting
+
+### Check connection status
+
+Use `status` to see connected clients. A healthy connection shows one client from the user's hostname with a recent `lastPong` timestamp.
+
+### Stale connections causing timeouts
+
+Use `kick_all` to reset -- active Adom Bridge apps reconnect within seconds.
+
+### No desktop client connected
+
+1. Confirm the Adom Bridge app is running on the user's PC
+2. Confirm it's pointed at the correct WebSocket URL
+3. Check if port 8765 is exposed and reachable
+
+### Relay not running
+
+```bash
+curl -sf http://127.0.0.1:8766/health
+# If fails: adom-bridge serve --supervise
+```
+
+### Shell commands on Windows
+
+`shell_execute` runs in `cmd.exe`. Prefer writing scripts via `send_files` then executing them. Use the full Python path.
+
+## Building from Source
+
+```bash
+cd cli && cargo build --release
+# Binary at: cli/target/release/adom-bridge
+```
+
+## Repo
+
+[github.com/adom-inc/adom-bridge](https://github.com/adom-inc/adom-bridge)
+
+## Run wiki ops on the user's PC — `wiki_exec` (v1.9.116+)
+
+The ab installer bundles the `adom-wiki` CLI next to the app, and `wiki_exec` runs it ON THE PC — so version-controlling a local project (KiCad board, docs folder) on wiki.adom.inc needs NO per-file `pull_file` round trip to the container and there is no container/PC drift.
+
+```bash
+adom-bridge wiki_exec '{"args":["repo","push","adom/my-board","--files","board.kicad_pcb","board.kicad_sch","-m","rev B"],"cwd":"C:\Users\me\boards\my-board"}'
+```
+
+- `args` = adom-wiki argv (any pillar: repo, pkg, release, discussion). `cwd` = PC-side project dir so `--files` are project-relative. `timeoutSec` optional (default 120, max 600).
+- Returns `{success, exitCode, timedOut, stdout, stderr, exe, durationMs}`.
+- Auth is automatic: ab injects the signed-in user's session token as `ADOM_WIKI_TOKEN` — the caller never handles credentials.
+- Gated like `shell_execute` for relay callers (it writes to the wiki as the user). `errorCode:wiki_cli_missing` means the desktop ab predates 1.9.116.
+- Container-side publishing of the CONTAINER's own files still uses your local `adom-wiki` directly; `wiki_exec` is for files that live on the PC.
+
+Note (v1.9.117): ab's Settings panel no longer has a KiCad section — bridges own their app-specific config (ab stays generic). `kicad_library_paths` / `project_watch` keep working from `~/.adom/config.json` and the `set_project_watch` / `trigger_project_watch` verbs.