@houwert/conductor 0.21.0 → 0.23.0

package/skills/conductor-device-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conductor-device-setup
-description: Boot, list, and manage devices and app installs for the conductor CLI — iOS simulators, Android emulators, tvOS simulators, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, installing or launching an app, setting up the web driver, keeping the driver warm, or coordinating multiple devices for parallel agents.
+description: Boot, list, and manage devices and app installs for the conductor CLI — iOS simulators, Android emulators, tvOS simulators, Vega (Amazon Fire TV) virtual devices, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, attaching to a Vega VVD, installing or launching an app, setting up the web driver, attaching to an already-running browser over CDP (e.g. an Electron app / its webviews), keeping the driver warm, or coordinating multiple devices for parallel agents.
 ---
 
 # Conductor — device & app setup
@@ -19,27 +19,58 @@ conductor list-apps          # installed app ids / package names
 
 ## Devices
 
-| Command | Purpose |
-|---|---|
-| `conductor start-device --platform <ios\|android\|tvos\|web>` | Boot a simulator/emulator or start the web driver |
-| `conductor start-device --os-version <n> --device-type <name>` | Pick OS version + device type (creates if needed) |
-| `conductor stop-device [<name-or-id>] [--all]` | Shut down device(s) |
-| `conductor delete-device <name-or-id> [--all]` | Delete simulator(s)/AVD(s)/web session(s) |
-| `conductor set-location --lat <n> --lng <n>` | Set GPS coordinates |
-| `conductor set-orientation <portrait\|landscape>` | Set orientation |
-| `conductor set-viewport [<w> <h>] [--preset mobile\|tablet\|desktop]` | Resize web viewport (web only) |
-| `conductor install-web [--check] [browser]` | Install a Playwright browser (chromium/firefox/webkit); `--check` = status |
+| Command                                                               | Purpose                                                                    |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `conductor start-device --platform <ios\|android\|tvos\|web\|vega>`   | Boot a simulator/emulator, start the web driver, or attach to a Vega VVD    |
+| `conductor start-device --os-version <n> --device-type <name>`        | Pick OS version + device type (creates if needed)                          |
+| `conductor stop-device [<name-or-id>] [--all]`                        | Shut down device(s)                                                        |
+| `conductor delete-device <name-or-id> [--all]`                        | Delete simulator(s)/AVD(s)/web session(s)                                  |
+| `conductor set-location --lat <n> --lng <n>`                          | Set GPS coordinates                                                        |
+| `conductor set-orientation <portrait\|landscape>`                     | Set orientation                                                            |
+| `conductor set-viewport [<w> <h>] [--preset mobile\|tablet\|desktop]` | Resize web viewport (web only)                                             |
+| `conductor install-web [--check] [browser]`                           | Install a Playwright browser (chromium/firefox/webkit); `--check` = status |
+
+### Attach to an existing browser (CDP)
+
+Instead of launching its own browser, the web driver can attach to one that's
+already running and exposes CDP over a remote-debugging port — e.g. an Electron
+app started with `--remote-debugging-port`, where each window / webview is a
+separate page target you can drive independently.
+
+| Command                                                                            | Purpose                                                                                                          |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `conductor web-targets --cdp-url <url>`                                            | List the controllable page targets the browser exposes (id, url, title) + a paste-ready bind command for each    |
+| `conductor --device web:<browser>:<label> --cdp-url <url> --cdp-target <id> <cmd>` | Bind a session to one target; the attachment persists so later commands for that `--device` don't need the flags |
+
+Use a distinct fully-qualified `--device web:chromium:<label>` per target (a bare
+`web` gets an auto-generated sub-id instead). Each target is its own session, so
+several webviews can be driven concurrently. Only `type=page` targets are
+controllable. See [Web testing → Attaching to an existing browser](../../../docs/web.md).
+
+### Vega (Amazon Fire TV)
+
+Vega is a React Native OS driven through Amazon's own `vega`/`kepler` CLI (not
+adb/simctl) — install the Vega SDK and put the CLI on `PATH` (or set
+`CONDUCTOR_VEGA_CLI`). `conductor start-device --platform vega` boots a Vega
+Virtual Device (VVD) via `vega virtual-device start` (or attaches if one is
+already running); pass `--name <vvd>` to pick a specific one. Devices show up in
+`list-devices` as `vega:<serial>`. The VVD's
+**developer mode** must be on for input, and the automation toolkit attaches at
+app launch — so launch the app under test via conductor. Navigate with the D-pad
+(`press-key "Remote Dpad …"` / `"Remote Dpad Center"`); coordinate `tap-on` also
+works. Unsupported on Vega: deep links (`open-link`), `set-location`, gestures,
+screen recording, clipboard, `clear-state`/`uninstall-app`.
 
 ## App lifecycle
 
-| Command | Purpose |
-|---|---|
-| `conductor install-app <path>` | Install .app / .ipa / .apk |
-| `conductor launch-app <appId>` | Launch app (saved to session); `--no-stop-app`, `--argument key=value` |
-| `conductor stop-app [<appId>]` | Stop app |
-| `conductor uninstall-app <appId>` | Uninstall app |
-| `conductor copy-app <bundleId> --from <id> --to <id>` | Copy an installed app between iOS simulators |
-| `conductor download-app <appId> --output <path>` | Download installed app binary |
+| Command                                               | Purpose                                                                |
+| ----------------------------------------------------- | ---------------------------------------------------------------------- |
+| `conductor install-app <path>`                        | Install .app / .ipa / .apk                                             |
+| `conductor launch-app <appId>`                        | Launch app (saved to session); `--no-stop-app`, `--argument key=value` |
+| `conductor stop-app [<appId>]`                        | Stop app                                                               |
+| `conductor uninstall-app <appId>`                     | Uninstall app                                                          |
+| `conductor copy-app <bundleId> --from <id> --to <id>` | Copy an installed app between iOS simulators                           |
+| `conductor download-app <appId> --output <path>`      | Download installed app binary                                          |
 
 ### ⚠️ Destructive flags — ask the user first
 
@@ -54,15 +85,15 @@ you genuinely need one, ask the human first.
 A **session** remembers the last device + app so you don't re-specify them.
 Parallel agents each get their own `--session <name>` so they don't collide.
 
-| Command | Purpose |
-|---|---|
-| `conductor session [--clear] [--list]` | Show, clear, or list sessions |
-| `conductor daemon-start` | Start the per-session background daemon (keeps the driver warm — do this for any multi-step session) |
-| `conductor daemon-status` | Show daemon status |
-| `conductor daemon-stop [--all]` | Stop this session's daemon (`--all` = every session) |
-| `conductor device-pool --list` | List devices + pool status |
-| `conductor device-pool --acquire` | Claim a free device (prints id) |
-| `conductor device-pool --release <id>` | Release a device back to the pool |
+| Command                                | Purpose                                                                                              |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `conductor session [--clear] [--list]` | Show, clear, or list sessions                                                                        |
+| `conductor daemon-start`               | Start the per-session background daemon (keeps the driver warm — do this for any multi-step session) |
+| `conductor daemon-status`              | Show daemon status                                                                                   |
+| `conductor daemon-stop [--all]`        | Stop this session's daemon (`--all` = every session)                                                 |
+| `conductor device-pool --list`         | List devices + pool status                                                                           |
+| `conductor device-pool --acquire`      | Claim a free device (prints id)                                                                      |
+| `conductor device-pool --release <id>` | Release a device back to the pool                                                                    |
 
 Don't leave a daemon running when you're done — `daemon-stop` it.