agent-device 0.13.2 → 0.14.0

package/skills/agent-device/references/exploration.md

@@ -1,362 +0,0 @@
-# Exploration
-
-## When to open this file
-
-Open this file when the app or screen is already running and you need to discover the UI, choose targets, read state, wait for conditions, or perform normal interactions.
-
-## Read-only first
-
-- If the question is what text, labels, or structure is visible on screen, start with plain `snapshot`.
-- Escalate to `snapshot -i` only when you need refs such as `@e3` for interactive exploration or a requested action.
-- If you intend to `press`, `fill`, or otherwise interact, start with `snapshot -i` and fall back to plain `snapshot` only if interactive refs are unavailable.
-- Prefer `get`, `is`, or `find` before mutating the UI when a read-only command can answer the question.
-- You may take the smallest reversible UI action needed to unblock inspection, such as dismissing a popup, closing an alert, or backing out of an unintended surface.
-- Do not type or fill text just to make hidden information easier to access unless the user asked for that interaction.
-- Do not use external sources to infer missing UI state unless the user explicitly asked.
-- If the answer is not visible or exposed in the UI, report that gap instead of compensating with search, navigation, or text entry.
-
-## Decision shortcut
-
-- User asks what is visible on screen: `snapshot`
-- User asks for exact text from a known target: `get text`
-- User asks you to tap, type, or choose an element: `snapshot -i`, then act
-- User asks for the React Native component tree, props/state/hooks, or render profiling: use `agent-device react-devtools ...` and the `skills/react-devtools` workflow
-- User asks to reload a Metro-backed React Native app after JS changes: `agent-device metro reload`, then wait briefly and re-run `snapshot` or `snapshot -i`
-- React Native dev or debug build shows warning/error UI: capture enough evidence to identify it, dismiss it if it is not the requested behavior, then continue the flow and report it in the summary
-- The on-screen keyboard is blocking the next step: `keyboard dismiss`; on iOS do this only while an app session is active, and use `keyboard status|get` only on Android
-- UI does not expose the answer: say so plainly; do not browse or force the app into a new state unless asked
-
-## Read-only commands
-
-- `snapshot`
-- `get`
-- `is`
-- `find`
-- `keyboard status|get` on Android when keyboard visibility or input type matters
-
-## Interaction commands
-
-- `snapshot -i`
-- `press`
-- `fill`
-- `type`
-- `scroll`
-- `wait`
-- `keyboard dismiss` when the keyboard obscures the next target
-
-## Common mistakes to avoid
-
-**Stale refs.** Do not treat `@ref` values as durable after navigation or dynamic updates. Re-snapshot after the UI changes, and switch to selectors when the flow must stay stable.
-
-**Android AX tree lag.** After submits, route changes, or composer transitions, the accessibility tree can lag behind the visible UI. If `snapshot -i` and `screenshot` disagree:
-
-1. Trust the screenshot as visual truth.
-2. Take one fresh `snapshot -i`. Android retries suspicious trees for a short post-action deadline after navigation-sensitive actions.
-3. If the tree still disagrees with the screenshot, wait briefly, then take one more fresh snapshot. Do not loop snapshots immediately.
-4. For animation-heavy Android runs, use `settings animations off` as an opt-in stabilizer and restore with `settings animations on` after the run.
-
-**React Native dev overlays.** In dev or debug builds, warning or error overlays can block taps, change focus, or hide the real UI. Check for them near app open and after major transitions.
-
-- Not blocking the task: dismiss and continue.
-- Blocking or recurring: switch to [debugging.md](debugging.md) and collect evidence.
-- Seen at any point: mention in the final summary even if dismissed.
-
-**React Native Metro reload.** When a dev app is already running and connected to Metro, prefer a Metro reload over restarting the native app process:
-
-```bash
-agent-device metro reload
-agent-device wait 1000
-agent-device snapshot -i
-```
-
-Use `--metro-host`, `--metro-port`, or `--bundle-url` only when the active connection does not already carry the right runtime hints. Fall back to `open <app> --relaunch` when the app is not connected to Metro, Metro reload fails, or native startup state needs a clean process.
-
-## Common example loops
-
-These are examples, not required exact sequences. Adapt them to the app, state, and task at hand.
-
-### Interactive exploration loop
-
-```bash
-agent-device open Settings --platform ios
-agent-device snapshot -i
-agent-device press @e3
-agent-device wait visible 'label="Privacy & Security"' 3000
-agent-device get text 'label="Privacy & Security"'
-agent-device close
-```
-
-### Screen verification loop
-
-```bash
-agent-device open MyApp --platform ios
-# perform the necessary actions to reach the state you need to verify
-agent-device snapshot
-# verify whether the expected element or text is present
-agent-device close
-```
-
-## Snapshot choices
-
-- Use plain `snapshot` when you only need to verify whether visible text or structure is on screen.
-- Use `snapshot -i` when you need refs such as `@e3` for interactive exploration or for an intended interaction.
-- On iOS and Android, default snapshot output is visible-first. Off-screen interactive content is surfaced as discovery hints (including inline scroll/list hidden-content hints when known), not shown as directly tappable refs.
-- Treat large text-surface lines in `snapshot -i` as discovery output. If a node shows preview or truncation metadata, use `get text @ref` only after you have already decided that `snapshot -i` is needed for that surface.
-- Use `snapshot -i -s "Camera"` or `snapshot -i -s @e3` when you want a smaller, scoped result.
-- If `snapshot -i -s "<query>"` returns 0 nodes, the scope did not match the current screen. Widen the query or re-check the screen state instead of assuming the command silently fell back to the full tree.
-- If `snapshot -i` returns 0 nodes but the screen is visibly populated, treat `screenshot` as visual truth, wait briefly, then re-run `snapshot -i` once before escalating.
-- If `snapshot -i -d <n>` says the interactive output is empty at that depth, retry without `-d` instead of taking more shallow snapshots.
-
-Example:
-
-```bash
-agent-device snapshot -i
-```
-
-Sample output:
-
-```text
-Page: com.apple.Preferences
-App: com.apple.Preferences
-
-@e1 [ioscontentgroup]
-  @e2 [button] "Camera"
-  @e3 [button] "Privacy & Security"
-[off-screen below] 2 interactive items: "Location Services", "Battery"
-```
-
-## Refs vs selectors
-
-- Use refs for discovery, debugging, and short local loops.
-- When a target appears only in a visible-first off-screen summary, such as `[off-screen below] ... "Battery"`, use `scroll down` and then `snapshot -i`. For `[off-screen above]`, use `scroll up` and then `snapshot -i`.
-- For more than two repeated scroll checks, create a short shell loop instead of issuing each command by hand. Stop when the label appears or the snapshot stops changing.
-- Visible-first off-screen summaries are intentionally compact. If you need the full off-screen tree instead of a short summary, retry with `snapshot --raw`.
-- Cap long searches in the loop when the list may be unbounded or the target may not exist.
-- Use selectors for deterministic scripts, assertions, and replay-friendly actions.
-- Prefer selector or `@ref` targeting over raw coordinates.
-- For tap interactions, `press` is canonical and `click` is an equivalent alias.
-
-Examples:
-
-```bash
-agent-device press @e2
-agent-device fill @e5 "test"
-agent-device press 'id="camera_row" || label="Camera" role=button'
-agent-device is visible 'id="camera_settings_anchor"'
-```
-
-Example loop:
-
-```bash
-previous=''
-for _ in 1 2 3 4 5 6; do
-  current="$(agent-device snapshot -i)"
-  printf '%s\n' "$current"
-  printf '%s\n' "$current" | grep -q 'Battery' && break
-  [ "$current" = "$previous" ] && break
-  previous="$current"
-  agent-device scroll down 0.5 >/dev/null
-done
-```
-
-## Interaction fallbacks
-
-When `press @ref` fails:
-
-1. If the error says the ref is off-screen, use the off-screen summary direction to run `scroll <direction>`, then take a fresh `snapshot -i`.
-2. Re-snapshot if the UI may have changed.
-3. Retry `press @ref` or a selector-based `press`.
-4. If `screenshot --overlay-refs --json` returned a reliable `overlayRefs[].center`, use `agent-device press <x> <y>`.
-5. Use an external vision-based tap tool only after semantic and coordinate targeting fail.
-
-- Prefer `@ref` over coordinates.
-- Do not guess coordinates from the image when structured `center` is available.
-- `agent-device` does not provide a built-in vision-tap flag.
-
-## Text entry rules
-
-- Use `fill` to replace text in an editable field.
-- Use `type` to append text to the current insertion point.
-- Use `fill @ref "text"` when you need to target a field directly by ref.
-- Use `press @ref`, then `type "text"` when the field is already focused and you need append semantics.
-- Do not write `type @ref "text"`; `type` only accepts text and will not target that ref for you.
-- If the keyboard blocks the next control after text entry, prefer `keyboard dismiss` instead of backing out of the screen.
-- On iOS, `keyboard dismiss` depends on the active app session to keep the target app foregrounded, so do not rely on selector-only dismiss calls after closing or without `open`.
-- Do not use `fill` or `type` just to make the app reveal information that is not currently visible unless the user asked for that interaction.
-
-## React Native dev or debug overlays
-
-Use this loop for React Native dev clients, Metro-backed builds, and local debug sessions where warnings or errors may appear as tooltips, banners, toasts, or modal overlays.
-
-1. After `open`, inspect the visible UI for warning or error surfaces before relying on the next tap.
-2. If a warning or error is visible, capture enough evidence to identify it:
-   - preferred: `screenshot`
-   - optional: `logs mark "warning visible"` or `logs mark "error visible"` if you are already in a debug window
-3. If the overlay is not the thing the user asked you to investigate, dismiss or close it with the smallest reversible action.
-4. Re-check the intended screen before continuing the task.
-5. Report any visible warnings or errors in the final summary, even if the flow succeeded after dismissal.
-
-Use this rule of thumb:
-
-- Warning overlay that does not block the task: dismiss and keep going.
-- Error overlay that does not block the task: dismiss, keep going, and report it.
-- Error overlay that blocks the task or keeps returning: stop treating it as noise and switch to [debugging.md](debugging.md).
-
-## Query and sync rules
-
-- Use `get` to read text, attrs, or state from a known target.
-- Use `is` for assertions.
-- Use `wait` when the UI needs time to settle after a mutation.
-- Use `find "<query>" click --json` when you need search-driven targeting plus matched-target metadata.
-- Use `find "<query>" click --first` or `--last` when ambiguous matches are expected and you want the first or last occurrence without falling back to raw coordinates.
-- If you are forced onto raw coordinates, open [coordinate-system.md](coordinate-system.md) first.
-
-Example:
-
-```bash
-agent-device find "Increment" click --json
-```
-
-Returned metadata comes from the matched snapshot node and can be used for observability or replay maintenance.
-
-## QA from acceptance criteria
-
-Use this loop when the task starts from acceptance criteria and you need to turn them into concrete checks.
-
-Preferred mapping:
-
-- visibility claim for what is on-screen now: `is visible` or plain `snapshot`
-- presence claim regardless of viewport visibility: `is exists`
-- exact text, label, or value claim: `get text`
-- post-action state change: act, then `wait`, then `is` or `get`
-- nearby structural UI change: `diff snapshot`
-- proof artifact for the final result: `screenshot` or `record`
-
-Notes:
-
-- `wait text` is useful for synchronizing on text presence, but it is not the same as `is visible`.
-- After a nearby navigation or submit on Android, prefer `screenshot`, then one fresh `snapshot -i`; `@ref` interactions refresh while the Android freshness window is active.
-
-Anti-hallucination rules:
-
-- Do not invent app names, device ids, session names, refs, selectors, or package names.
-- Discover them first with `devices`, `open`, `snapshot -i`, `find`, or `session list`.
-- If refs drift after navigation, re-snapshot or switch to selectors instead of guessing.
-
-Avoid this escalation path for visible-text questions:
-
-- Do not jump from `snapshot -i` to `get text @ref`, then to web search, then to typing into a search box just to force the app to reveal the answer.
-- Start with `snapshot`. If the text is not visible or exposed, report that directly.
-- After Android submit or navigation-heavy actions when the UI looks wrong: `screenshot` first, then `snapshot -i`.
-
-Canonical QA loop:
-
-```bash
-agent-device open MyApp --platform ios
-agent-device snapshot -i
-agent-device press @e3
-agent-device wait visible 'label="Success"' 3000
-agent-device is visible 'label="Success"'
-agent-device screenshot /tmp/qa-proof.png
-agent-device close
-```
-
-## Accessibility audit
-
-Use this pattern when you need to find UI that is visible to a user but missing from the accessibility tree.
-
-Audit loop:
-
-1. Capture a `screenshot` to see what is visually rendered.
-2. Capture a `snapshot` or `snapshot -i` to see what the accessibility tree exposes.
-3. Compare the two:
-   - visible in screenshot and present in snapshot: exposed to accessibility
-   - visible in screenshot and missing from snapshot: likely accessibility gap
-4. If you suspect the node exists in AX but is filtered from interactive output, retry with `snapshot --raw`.
-
-Example:
-
-```bash
-agent-device screenshot /tmp/accessibility-screen.png
-agent-device snapshot -i
-```
-
-Use `screenshot` as the visual source of truth and `snapshot` as the accessibility source of truth for this audit.
-
-## Batch only when the sequence is already known
-
-Use `batch` when a short command sequence is already planned and belongs to one logical screen flow.
-
-```bash
-agent-device batch --session sim --platform ios --steps-file /tmp/batch-steps.json --json
-```
-
-- Keep batch size moderate, roughly 5 to 20 steps.
-- Add `wait` or `is exists` guards after mutating steps.
-- Do not use `batch` for highly dynamic flows that need replanning after each step.
-
-Example: known chat-send flow
-
-```json
-[
-  { "command": "open", "positionals": ["ChatApp"], "flags": { "platform": "android" } },
-  { "command": "click", "positionals": ["label=\"Travel chat\""], "flags": {} },
-  { "command": "wait", "positionals": ["label=\"Message\"", "3000"], "flags": {} },
-  { "command": "fill", "positionals": ["label=\"Message\"", "Filed the expense"], "flags": {} },
-  { "command": "press", "positionals": ["label=\"Send\""], "flags": {} }
-]
-```
-
-Step payload contract:
-
-```json
-[
-  { "command": "open", "positionals": ["Settings"], "flags": { "platform": "ios" } },
-  { "command": "wait", "positionals": ["label=\"Privacy & Security\"", "3000"], "flags": {} },
-  { "command": "click", "positionals": ["label=\"Privacy & Security\""], "flags": {} },
-  { "command": "get", "positionals": ["text", "label=\"Tracking\""], "flags": {} }
-]
-```
-
-- `positionals` is optional and defaults to `[]`.
-- `flags` is optional and defaults to `{}`.
-- Only `command`, `positionals`, `flags`, and `runtime` are accepted as top-level step keys.
-- Nested `batch` and `replay` are rejected.
-- Supported error mode is stop-on-first-error.
-
-Response handling:
-
-- Success returns fields such as `total`, `executed`, `totalDurationMs`, and `results[]`.
-- Human-mode `batch` runs also print a short per-step success summary.
-- Failed runs include `details.step`, `details.command`, `details.executed`, and `details.partialResults`.
-- Replan from the first failing step instead of rerunning the whole flow blindly.
-
-Canonical batch recipe: open app -> open action menu -> choose option -> verify
-
-```json
-[
-  { "command": "open", "positionals": ["com.example.app"], "flags": { "platform": "android" } },
-  { "command": "wait", "positionals": ["text", "Home", "3000"], "flags": {} },
-  { "command": "press", "positionals": ["label=\"More actions\" role=button"], "flags": {} },
-  { "command": "wait", "positionals": ["text", "Camera scan", "2000"], "flags": {} },
-  { "command": "press", "positionals": ["label=\"Camera scan\""], "flags": {} },
-  { "command": "wait", "positionals": ["text", "Expense created", "15000"], "flags": {} },
-  { "command": "is", "positionals": ["visible", "label=\"Expense created\""], "flags": {} }
-]
-```
-
-Common batch error categories:
-
-- `INVALID_ARGS`: fix the payload shape and retry.
-- `SESSION_NOT_FOUND`: open or select the correct session, then retry.
-- `UNSUPPORTED_OPERATION`: switch to a supported command or surface.
-- `AMBIGUOUS_MATCH`: refine the selector or locator, then retry the failed step.
-- `DEVICE_IN_USE`: the device is held by another session — close or reuse the existing session before retrying.
-- `COMMAND_FAILED`: add sync guards and retry from the failing step.
-
-## Stop conditions
-
-- If refs drift after transitions, switch to selectors.
-- If a desktop surface or context menu is involved on macOS, load [macos-desktop.md](macos-desktop.md).
-- If logs, network, alerts, or setup failures become the blocker, switch to [debugging.md](debugging.md).
-- If the flow is stable and you need proof or replay maintenance, switch to [verification.md](verification.md).

package/skills/agent-device/references/macos-desktop.md

@@ -1,88 +0,0 @@
-# macOS Desktop
-
-## When to open this file
-
-Open this file only when `--platform macos` is involved or the task needs `frontmost-app`, `desktop`, or `menubar` surfaces.
-
-## Main commands to reach for first
-
-- `open <app> --platform macos`
-- `open --platform macos --surface frontmost-app|desktop|menubar`
-- `snapshot -i`
-- `get`
-- `is`
-- `click --button secondary`
-
-## Most common mistake to avoid
-
-Do not treat every macOS surface the same. Use the normal `app` surface when you want to act inside one app. Use `frontmost-app`, `desktop`, or `menubar` mainly to inspect what is visible before switching back to `app` for most interactions.
-
-## Canonical loop
-
-```bash
-agent-device open TextEdit --platform macos
-agent-device snapshot
-agent-device close
-```
-
-## Surface rules
-
-- `app`: default surface and the normal choice for `click`, `fill`, `press`, `scroll`, `screenshot`, and `record`.
-- `frontmost-app`: inspect the currently focused app without naming it first.
-- `desktop`: inspect visible desktop windows across apps.
-- `menubar`: inspect the active app menu bar and system menu extras. Use `open <app> --platform macos --surface menubar` when you need one menu bar app's extras, such as a status-item app.
-- Menu bar apps can expose a sparse or empty default `app` tree. Prefer the `menubar` surface first when the app lives entirely in the top bar.
-
-Use inspect-first surfaces to understand desktop-global UI, then switch back to `app` when you need to act in one app.
-
-## Snapshot expectations
-
-- `snapshot -i` should describe UI visible to a human.
-- `desktop` snapshots can include multiple windows from multiple apps.
-- `menubar` snapshots can include both app-menu items and system menu extras.
-- Finder-style rows, sidebar items, toolbar controls, search fields, and opened context menus should appear when visible.
-- Finder and other native apps may expose duplicate-looking row, cell, and child text nodes. Treat them as distinct AX nodes unless you have a stronger selector anchor.
-
-## Context menus
-
-Context menus are not ambient UI. Open them explicitly, then re-snapshot.
-
-```bash
-agent-device click @e66 --button secondary --platform macos
-agent-device snapshot -i
-```
-
-Expected loop:
-
-1. Snapshot visible content.
-2. Secondary-click the target item.
-3. Snapshot again.
-4. Interact with the new `menu-item` nodes.
-
-## Targeting rules
-
-- Prefer selectors or `@ref` values over raw coordinates.
-- On macOS, window position can vary across runs, so coordinate-only flows are fragile.
-- If the task only needs shared exploration rules, return to [exploration.md](exploration.md).
-
-Selector guidance:
-
-- Good selectors usually anchor on stable labels or app-owned identifiers such as `label="Downloads"` or `role=menu-item label="Rename"`.
-- Avoid relying on framework-generated `_NS:*` identifiers as stable selectors.
-
-Use `snapshot --raw --platform macos` only when debugging AX structure or collector filtering. Do not make raw snapshots the default agent loop.
-
-Things not to rely on:
-
-- Mobile-only helpers such as `install`, `reinstall`, or `push`.
-- Desktop-global click, fill, or gesture parity from `desktop` or `menubar` sessions.
-- Raw coordinate assumptions across runs.
-
-Troubleshooting:
-
-- If visible content is missing from `snapshot -i`, re-snapshot after the UI settles.
-- If `desktop` is too broad, retry with `frontmost-app`.
-- If `menubar` is missing the expected menu, retry with `open <app> --platform macos --surface menubar` for menu bar apps, or make the app frontmost first and retry the generic menubar surface.
-- If the wrong menu opened, retry secondary-clicking the row or cell wrapper rather than the nested text node.
-- If the app has multiple windows, make the correct window frontmost before relying on refs.
-- If overriding the local helper, set `AGENT_DEVICE_MACOS_HELPER_BIN` to an absolute executable path; relative helper paths are rejected.

package/skills/agent-device/references/remote-tenancy.md

@@ -1,188 +0,0 @@
-# Remote Tenancy
-
-## When to open this file
-
-Open this file for remote daemon HTTP flows that let an agent running in a Linux sandbox talk to another `agent-device` instance on a remote macOS host in order to control devices that are not available locally. This file covers daemon URL setup, authentication, `connect`, tenant lease scope, and remote Metro companion lifecycle.
-
-## Main commands to reach for first
-
-- `agent-device connect --remote-config <path>`
-- `agent-device install-from-source <url> --remote-config <path> --platform android`
-- `agent-device install-from-source --github-actions-artifact <org>/<repo>:<artifact> --remote-config <path> --platform android`
-- `agent-device open <package> --remote-config <path> --relaunch`
-- `agent-device metro reload --remote-config <path>`
-- `agent-device snapshot --remote-config <path> -i`
-- `agent-device disconnect --remote-config <path>`
-- `agent-device connection status`
-- `agent-device auth status`
-- `AGENT_DEVICE_DAEMON_AUTH_TOKEN=...` for CI/service-token automation
-
-## Most common mistake to avoid
-
-Do not mix an arbitrary `--session` plus ad-hoc daemon, tenant, run, or lease flags. That can bypass saved Metro runtime hints. Use one of these patterns instead:
-
-- Interactive flow: run `connect --remote-config <path>` once, then normal commands, then `disconnect`.
-- Script flow: pass the same `--remote-config <path>` to every command, including `disconnect`.
-
-## Choose one flow
-
-### Interactive flow
-
-Use this when the agent will run several commands in one session.
-
-```bash
-agent-device connect --remote-config ./remote-config.json
-
-ARTIFACT_URL="<trusted-artifact-url>"
-agent-device install-from-source "$ARTIFACT_URL" --platform android
-agent-device open com.example.app --relaunch
-agent-device metro reload
-agent-device snapshot -i
-agent-device fill @e3 "test@example.com"
-agent-device disconnect
-```
-
-After `connect`, normal commands use the active remote connection. If cloud credentials are missing, `connect` starts login automatically in an interactive shell and stores a revocable CLI session that silently mints short-lived `adc_agent_...` command tokens. The cloud side remains responsible for token expiry, tenant/run claim checks, revocation, one-time device approval, and polling rate limits. End with `disconnect` to release the lease and stop the owned Metro companion.
-
-### Self-contained script flow
-
-Use this when each command must be explicit and repeatable. Pass the same `--remote-config` to each step.
-
-```bash
-ARTIFACT_URL="<trusted-artifact-url>"
-
-agent-device install-from-source "$ARTIFACT_URL" \
-  --remote-config ./remote-config.json \
-  --platform android
-
-agent-device open com.example.app \
-  --remote-config ./remote-config.json \
-  --relaunch
-
-agent-device snapshot \
-  --remote-config ./remote-config.json \
-  -i
-
-agent-device disconnect \
-  --remote-config ./remote-config.json
-```
-
-The first command that needs a lease or Metro runtime prepares and persists it. Later commands with the same `--remote-config` reuse that state. End with `disconnect --remote-config <path>` to release the lease and stop the owned Metro companion.
-
-## Behavior summary
-
-- `connect` stores local non-secret connection state and defers tenant lease allocation plus Metro preparation until a later command needs them.
-- Commands such as `install-from-source`, `open`, `snapshot`, and `apps` allocate or refresh the lease when needed.
-- `open` prepares Metro runtime hints when the remote profile has Metro fields and no compatible runtime is already saved.
-- `metro reload` reuses saved Metro runtime hints and asks Metro to reload connected React Native apps without restarting the native process.
-- `batch` also prepares Metro when any step opens an app and that step does not provide its own runtime.
-- `disconnect` closes the session when possible, stops the Metro companion owned by the connection, releases the lease when one was allocated, and removes local connection state.
-
-Remote install examples:
-
-```bash
-agent-device install com.example.app ./app.apk
-ARTIFACT_URL="<trusted-artifact-url>"
-agent-device install-from-source "$ARTIFACT_URL" --platform android
-```
-
-- Use `install` or `reinstall` for local paths; remote daemons upload local artifacts automatically.
-- Use `install-from-source` only for trusted, operator-approved artifact URLs the remote daemon can reach. Do not fetch arbitrary user-supplied URLs.
-- Use `install-from-source --github-actions-artifact <org>/<repo>:<artifact>` when the remote daemon has repository credentials and supports daemon-resolved GitHub Actions artifacts.
-- For local-path versus URL artifact rules, follow [bootstrap-install.md](bootstrap-install.md).
-
-Use `agent-device connection status --session adc-android` to inspect the active connection without reading JSON state manually. Status output must not include auth tokens.
-
-## Remote config shape
-
-Example `remote-config.json` shape:
-
-```json
-{
-  "daemonBaseUrl": "https://bridge.example.com/agent-device",
-  "daemonTransport": "http",
-  "tenant": "acme",
-  "runId": "run-123",
-  "sessionIsolation": "tenant",
-  "platform": "ios",
-  "metroProxyBaseUrl": "https://bridge.example.com"
-}
-```
-
-Optional overrides stay available for advanced cases:
-
-```json
-{
-  "session": "adc-ios",
-  "leaseBackend": "ios-instance",
-  "metroProjectRoot": ".",
-  "metroKind": "expo",
-  "metroPublicBaseUrl": "http://127.0.0.1:8081"
-}
-```
-
-- Keep service tokens in env/config managed by the operator boundary. Do not persist auth tokens in connection state. Human login uses `agent-device auth login` or implicit `connect` login and stores only the CLI session credential.
-- Omit Metro fields for non-React Native flows.
-- Put `tenant`, `runId`, and `sessionIsolation` in the remote profile so agents can run `agent-device connect --remote-config ./remote-config.json` without extra scope flags. Add `platform`, `leaseBackend`, `session`, or Metro overrides only when the default inference is not enough for that flow.
-- Explicit command-line flags override connected defaults. Use them intentionally when switching session, platform, target, tenant, run, or lease scope.
-- For React Native Metro runs with `metroProxyBaseUrl`, `agent-device >= 0.11.12` can manage the local companion tunnel, but Metro itself still needs to be running locally. `metroProxyBaseUrl` is the bridge origin, not a prebuilt `/api/metro/...` route.
-- For cloud stock React Native iOS, use the bridge descriptor's wildcard HTTPS Metro hints directly; do not install or launch the XCTest runner just to make Metro reachable.
-- Android keeps using bridge-provided `/api/metro/runtimes/<runtimeId>/...` Metro routes.
-- `metroPublicBaseUrl` is only needed for direct/non-bridge bundle hints. Bridged profiles can omit it.
-- Use a lease backend that matches the bridge target platform, for example `android-instance`, `ios-instance`, or an explicit `--lease-backend` override.
-
-## Transport prerequisites
-
-- Start the daemon in HTTP mode with `AGENT_DEVICE_DAEMON_SERVER_MODE=http|dual` on the host.
-- Point the profile or env at the remote host with `daemonBaseUrl` or `AGENT_DEVICE_DAEMON_BASE_URL=http(s)://host:port[/base-path]`.
-- For humans, run `connect --remote-config <path>` and let it refresh or create the CLI session. Use `agent-device auth status` to inspect it and `agent-device auth logout` to remove it.
-- For CI/non-interactive shells, set `AGENT_DEVICE_DAEMON_AUTH_TOKEN=adc_live_...` or pass `--daemon-auth-token`. The client does not start device-code polling in CI by default.
-- Prefer an auth hook such as `AGENT_DEVICE_HTTP_AUTH_HOOK` when the host needs caller validation or tenant injection.
-
-## Lease debug fallback
-
-The main agent flow should use `connect` and `connection status`. For daemon-side auth, scope, or lease debugging, inspect host-side daemon logs and operator tooling instead of issuing raw daemon RPC from the agent shell.
-
-## GitHub Actions artifact install
-
-Use this when a compatible remote daemon resolves GitHub Actions artifacts server-side. Do not download CI artifacts locally or add a local `GITHUB_TOKEN` just to install CI output.
-
-Artifact ID shape:
-
-```bash
-agent-device install-from-source \
-  --github-actions-artifact OWNER/REPO:1234567890 \
-  --remote-config ./remote-config.json \
-  --platform android
-```
-
-Artifact-name shape:
-
-```bash
-agent-device install-from-source \
-  --github-actions-artifact OWNER/REPO:app-debug \
-  --remote-config ./remote-config.json \
-  --platform ios
-```
-
-Config shape:
-
-```json
-{
-  "installSource": {
-    "type": "github-actions-artifact",
-    "repo": "OWNER/REPO",
-    "artifact": "app-debug"
-  }
-}
-```
-
-Numeric artifacts are passed as artifact IDs. Non-numeric artifacts are passed as artifact names.
-
-## Failure semantics and trust notes
-
-- Missing tenant, run, or lease fields in tenant-isolation mode should fail as `INVALID_ARGS`.
-- Inactive or scope-mismatched leases should fail as `UNAUTHORIZED`.
-- Inspect logs on the remote host during remote debugging. Client-side `--debug` does not tail a local daemon log once `AGENT_DEVICE_DAEMON_BASE_URL` is set.
-- Do not point `AGENT_DEVICE_DAEMON_BASE_URL` at untrusted hosts. Remote daemon requests can launch apps and execute interaction commands.
-- Treat daemon auth tokens and lease identifiers as sensitive operational data.