Adom Bridge

@@ -1,201 +1,214 @@-----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. |+---
+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                    # ab-core catalog (args, returns, _hint per verb) + `bridges`: the box's installed bridges, live
+adom-bridge --target <name> commands    # the same, for THAT box
+adom-bridge commands '{"bridge":"fusion360"}'   # ONE bridge, described by the bridge itself (its <prefix>describe verb, else its manifest's verb list)
+adom-bridge help <topic>                # details for one ab-core verb or namespace (e.g. help shell); `help pup` / `help kicad` point at the bridge
+```
+
+**Bridge verbs are the bridge's to describe (2.1.144, wiki #211).** `commands` carries NO
+copy of any bridge's verbs: ab is the operating system, a bridge owns all of its verbs
+(John, 2026-08-19). The hand-written `fusion360` / `kicad` / `browser` sections ab used
+to print drifted (63 Fusion verbs listed against the bridge's 160, retired verbs still
+there, shipped verbs missing) and made an AI conclude a documented verb did not exist.
+Now `commands` appends `bridges` read live from the box (name, version, status,
+verbPrefixes, verbCount, verb names, `describeVerb`), and `commands {"bridge": name}`
+returns the bridge's own `<prefix>describe` answer (every verb with inputs, outputs,
+timeout) or, for a bridge without one, its manifest's verb list. The per-verb how-to is
+the bridge's skill: `sync_skills`.
+
+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 `bridges` in `commands` (was `installed_bridges_on_target` before
+  2.1.144), 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. |