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

adom-desktop commands            # full verb catalog (categories → verbs → args/returns)
adom-desktop status              # laptop state (installed apps, WSL health, …) — also surfaces the catalog

adompkg install adom/adom-desktop     # → ~/.local/bin/adom-desktop + the adom-desktop-* skills
adom-desktop --version                # confirm

---
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 --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-desktop targets` shows none) and you need to set one up, **run `adom-desktop 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-desktop 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 Desktop 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 AD's Connections → "Paste server JSON to add" box.

Either way, start the relay here so the desktop has something to dial: `adom-desktop serve --supervise`. Verify with `adom-desktop targets`.

## 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.