Adom Bridge

@@ -1,77 +1,77 @@-----name: adom-desktop-discovery-user-invocable: false-description: "Reaches the user's Windows/Mac laptop desktop from this container via adom-desktop — 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 (browser_screenshot, browser_eval, browser_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-desktop 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-desktop, bridge to my pc, windows app, KiCad bridge, Fusion bridge."------# adom-desktop — discovery & install--**This skill is a pointer.** When any trigger fires, confirm `adom-desktop` 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-desktop --version          # path + version, e.g. adom-desktop 1.8.163 (<sha>, built …)-adom-desktop ping               # {echo:"pong", status:"connected"} == the laptop is reachable-```--If `adom-desktop` isn't found → **§4 install**. If `ping` doesn't say `connected`, the relay isn't serving — start it: `adom-desktop serve &` (then re-`ping`).--## 2 — ⭐ DISCOVER THE VERB: `adom-desktop 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-desktop --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-desktop commands            # full verb catalog (categories → verbs → args/returns)-adom-desktop 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-AD relay: if you get `status:error` / `ambiguous_target`, pass `--target <name>` (list them with `adom-desktop 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-desktop 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-desktop     # → ~/.local/bin/adom-desktop + the adom-desktop-* skills-adom-desktop --version                # confirm-```--`adom-desktop status` reports the latest published version; if your local CLI is older, re-run `adompkg install adom/adom-desktop` to refresh the binary **and** the skills atomically. (Wiki page: `https://wiki.adom.inc/adom/adom-desktop`.) **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-desktop` (main) | the full verb reference + shell/process/file/window/WSL/tunnel patterns, status+durationMs result shape |-| `adom-desktop-pup` | Puppeteer real-Chrome automation (browser_open_window/navigate/screenshot/eval, multi-session profiles) |-| `adom-desktop-kicad` | KiCad bridge (open schematics/boards, DRC, library install, 3D viewer, automation) |-| `adom-desktop-fusion` | Fusion 360 bridge (.f3d/.f3z, STEP/GLB/.lbr import-export, BOM/params, Fusion API) |-| `adom-desktop-direct-api` | the loopback HTTP API for sibling apps (Hydrogen Desktop) |-| `adom-desktop-installer` | invoking the Windows installer (silent/NOLAUNCH) |--But you don't need to read those to act — **`adom-desktop commands` is always the live source of truth** for what verbs exist right now.--## 6 — Why this skill exists--adom-desktop 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-desktop commands`, the runtime catalog, instead of guessing.+---
+name: adom-desktop-discovery
+user-invocable: false
+description: "Reaches the user's Windows/Mac laptop desktop from this container via adom-desktop — 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 (browser_screenshot, browser_eval, browser_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-desktop 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-desktop, bridge to my pc, windows app, KiCad bridge, Fusion bridge."
+---
+
+# adom-desktop — discovery & install
+
+**This skill is a pointer.** When any trigger fires, confirm `adom-desktop` 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-desktop --version          # path + version, e.g. adom-desktop 1.8.163 (<sha>, built …)
+adom-desktop ping               # {echo:"pong", status:"connected"} == the laptop is reachable
+```
+
+If `adom-desktop` isn't found → **§4 install**. If `ping` doesn't say `connected`, the relay isn't serving — start it: `adom-desktop serve &` (then re-`ping`).
+
+## 2 — ⭐ DISCOVER THE VERB: `adom-desktop 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-desktop --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-desktop commands            # full verb catalog (categories → verbs → args/returns)
+adom-desktop 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-AD relay: if you get `status:error` / `ambiguous_target`, pass `--target <name>` (list them with `adom-desktop 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-desktop 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-desktop     # → ~/.local/bin/adom-desktop + the adom-desktop-* skills
+adom-desktop --version                # confirm
+```
+
+`adom-desktop status` reports the latest published version; if your local CLI is older, re-run `adompkg install adom/adom-desktop` to refresh the binary **and** the skills atomically. (Wiki page: `https://wiki.adom.inc/adom/adom-desktop`.) **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-desktop` (main) | the full verb reference + shell/process/file/window/WSL/tunnel patterns, status+durationMs result shape |
+| `adom-desktop-pup` | Puppeteer real-Chrome automation (browser_open_window/navigate/screenshot/eval, multi-session profiles) |
+| `adom-desktop-kicad` | KiCad bridge (open schematics/boards, DRC, library install, 3D viewer, automation) |
+| `adom-desktop-fusion` | Fusion 360 bridge (.f3d/.f3z, STEP/GLB/.lbr import-export, BOM/params, Fusion API) |
+| `adom-desktop-direct-api` | the loopback HTTP API for sibling apps (Hydrogen Desktop) |
+| `adom-desktop-installer` | invoking the Windows installer (silent/NOLAUNCH) |
+
+But you don't need to read those to act — **`adom-desktop commands` is always the live source of truth** for what verbs exist right now.
+
+## 6 — Why this skill exists
+
+adom-desktop 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-desktop commands`, the runtime catalog, instead of guessing.