agent-device 0.10.1 → 0.10.3

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

@@ -0,0 +1,115 @@
+# Debugging
+
+## When to open this file
+
+Open this file when the task turns into failure triage, logs, network inspection, permission prompts, setup trouble, or unstable session behavior.
+
+## Main commands to reach for first
+
+- `logs clear --restart`
+- `network dump`
+- `logs path`
+- `logs doctor`
+- `alert wait`
+- `alert accept` or `alert dismiss`
+
+## Most common mistake to avoid
+
+Do not leave logging on for normal flows or dump full log files into context. Keep debug windows short and inspect logs with `grep` or `tail`.
+
+## Canonical loop
+
+```bash
+agent-device open MyApp --platform ios
+agent-device logs clear --restart
+agent-device network dump 25
+agent-device logs path
+agent-device close
+```
+
+## Log and network flow
+
+Logging is off by default. Enable it only when you need a debugging window.
+
+- Default app logs live under `~/.agent-device/sessions/<session>/app.log`.
+- `logs clear --restart` is the fastest clean repro loop.
+- `network dump [limit] [summary|headers|body|all]` parses recent HTTP(s) entries from the same session app log.
+- `logs doctor` checks backend and runtime readiness for the current session and device.
+- `logs mark "before tap"` inserts a timestamped marker into the app log.
+- Session app logs can contain runtime data, headers, or payload fragments. Review them before sharing.
+- `logs start` requires an active app session and appends to `app.log`.
+- `logs stop` stops streaming. `close` also stops logging.
+- `logs clear` truncates `app.log` and removes rotated `app.log.N` files, and requires logging to be stopped first.
+- `logs path` returns the log path plus metadata about the active backend and file state.
+- `network log` is an alias for `network dump`.
+
+Operational limits:
+
+- `app.log` rotates to `app.log.1` after 5 MB by default.
+- `network dump` scans the last 4000 app-log lines, returns up to 200 entries, and truncates header or payload fields at 2048 characters.
+- Retention knobs:
+  - `AGENT_DEVICE_APP_LOG_MAX_BYTES`
+  - `AGENT_DEVICE_APP_LOG_MAX_FILES`
+- Redaction hook:
+  - `AGENT_DEVICE_APP_LOG_REDACT_PATTERNS`
+
+Useful shell follow-up after `logs path`:
+
+```bash
+grep -n -E "Error|Exception|Fatal|crash" <path>
+tail -50 <path>
+```
+
+## Alerts and permissions
+
+Use `alert` for iOS simulator permission dialogs instead of tapping coordinates.
+
+```bash
+agent-device alert wait 5000
+agent-device alert accept
+```
+
+- `alert` is only supported on iOS simulators.
+- `alert accept` and `alert dismiss` retry internally for a short window, so you usually do not need manual sleeps.
+- iOS 16+ "Allow Paste" prompts are suppressed under XCUITest. Use `xcrun simctl pbcopy booted` when you need to seed simulator clipboard content directly.
+
+## Setup problems worth recognizing early
+
+- iOS snapshots do not require macOS Accessibility permissions.
+- iOS physical-device XCTest setup does require valid signing and provisioning.
+- If physical-device runner setup fails, prefer Xcode Automatic Signing first.
+- Optional overrides are:
+  - `AGENT_DEVICE_IOS_TEAM_ID`
+  - `AGENT_DEVICE_IOS_SIGNING_IDENTITY`
+  - `AGENT_DEVICE_IOS_PROVISIONING_PROFILE`
+  - `AGENT_DEVICE_IOS_BUNDLE_ID`
+- If daemon startup is timing out during setup, increase `AGENT_DEVICE_DAEMON_TIMEOUT_MS`.
+- If daemon startup fails with stale metadata hints, clean `~/.agent-device/daemon.json` and `~/.agent-device/daemon.lock`, then retry.
+- Free Apple Developer personal-team accounts may reject generic bundle IDs. Use a unique reverse-DNS value for `AGENT_DEVICE_IOS_BUNDLE_ID` when that happens.
+
+## Common failure patterns
+
+- `snapshot` returns 0 nodes: the app may no longer be foregrounded or the UI is not stable yet. Re-open the app or retry when state settles.
+- Logs are empty: confirm you opened an app session before `logs clear --restart`.
+- Android logs look stale after relaunch: retry the repro window after the process rebinds.
+- Permission prompts block the flow: wait for the alert and handle it explicitly.
+- If snapshots keep returning 0 nodes on an iOS simulator, restart Simulator and re-open the app.
+- If a macOS snapshot looks incomplete, compare with `snapshot --raw --platform macos` to separate collector filtering from missing AX content.
+
+## Crash triage fast path
+
+Always start from the session app log, then branch by platform.
+
+```bash
+agent-device logs path
+grep -n -E "SIGABRT|SIGSEGV|EXC_|fatal|exception|terminated|killed|jetsam|memorystatus|FATAL EXCEPTION|Abort message" <path>
+```
+
+- iOS: if the log suggests `ReportCrash`, `SIGABRT`, or `EXC_*`, inspect `~/Library/Logs/DiagnosticReports`.
+- Android: if the app log is not enough, use `adb logcat` for `FATAL EXCEPTION`, `Abort message`, or `signal` lines around process death.
+- If no crash signature appears in app logs, stop collecting broad logs and switch to the platform-native crash source.
+
+## When to leave this file
+
+- Return to [exploration.md](exploration.md) once the app is stable again.
+- Load [verification.md](verification.md) if you need evidence artifacts after reproducing the issue.

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

@@ -0,0 +1,235 @@
+# 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
+- 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`
+
+## Interaction commands
+
+- `snapshot -i`
+- `press`
+- `fill`
+- `type`
+- `wait`
+
+## Most common mistake to avoid
+
+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.
+
+## 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.
+- 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.
+
+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"
+```
+
+## Refs vs selectors
+
+- Use refs for discovery, debugging, and short local loops.
+- 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"'
+```
+
+## Text entry rules
+
+- Use `fill` to replace text in an editable field.
+- Use `type` to append text to the current insertion point.
+- 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.
+
+## 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.
+- 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 or presence claim: `is visible` or plain `snapshot`
+- 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`
+
+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.
+
+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.
+
+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 `{}`.
+- 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[]`.
+- 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.
+
+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.
+- `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,89 +1,86 @@
-# macOS Desktop Automation
+# macOS Desktop
 
-Use this reference for host Mac apps such as Finder, TextEdit, System Settings, Preview, or browser apps running as normal desktop windows.
+## When to open this file
 
-## Mental model
+Open this file only when `--platform macos` is involved or the task needs `frontmost-app`, `desktop`, or `menubar` surfaces.
 
-- `snapshot -i` should describe UI that is visible to a human in the current front window.
-- Context menus are not ambient UI. Open them explicitly with `click --button secondary`, then re-snapshot.
-- Prefer refs for exploration and selectors for deterministic replay/assertions.
-- Avoid raw `x y` coordinates unless refs/selectors are impossible.
+## Main commands to reach for first
 
-## Canonical flow
+- `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 Finder --platform macos
-agent-device snapshot -i
-agent-device click @e66 --button secondary --platform macos
-agent-device snapshot -i
+agent-device open TextEdit --platform macos
+agent-device snapshot
 agent-device close
 ```
 
-## What to expect from snapshots
+## 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 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` prioritizes visible window content over dormant menu infrastructure.
-- File rows, sidebar items, toolbar controls, search fields, and visible context menus should appear.
-- Finder and other native apps may expose duplicate-looking structures such as row wrapper nodes, `cell` nodes, and child `text` or `text-field` nodes.
-- Treat those as distinct AX nodes unless you have a stronger selector anchor.
+- `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
 
-Use secondary click when the app exposes actions only through the contextual menu.
+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 pattern:
+Expected loop:
 
 1. Snapshot visible content.
-2. Secondary-click the target row/item.
+2. Secondary-click the target item.
 3. Snapshot again.
-4. Interact with newly visible `menu-item` nodes.
-
-Do not expect context-menu items to appear before the menu is opened.
-
-## Finder-specific guidance
-
-- `snapshot -i` should still expose visible folder rows even when nothing is selected.
-- Unselected folder contents should still be visible in `snapshot -i` through list/table rows.
-- A file row may expose multiple nodes with the same label, including a row container, name cell, and child text/text-field.
-- For opening a context menu, prefer the outer visible row/cell ref over a nested text child if both exist.
-- After secondary click, expect actions such as `Rename`, `Quick Look`, `Copy`, `Compress`, and tag-related items in the next snapshot.
-
-## Raw snapshots
-
-Use `snapshot --raw` only when debugging AX structure or collector issues.
-
-```bash
-agent-device snapshot --raw --platform macos
-```
+4. Interact with the new `menu-item` nodes.
 
-- Raw output is larger and less token-efficient.
-- It is useful for verifying whether missing UI is absent from the AX tree or only filtered from interactive output.
-- Do not use raw output as the default agent loop when `snapshot -i` already shows the visible window content you need.
+## Targeting rules
 
-## Selector guidance
+- 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).
 
-Good macOS selectors usually anchor on one of:
+Selector guidance:
 
-- `label="Downloads"`
-- `label="failed-step.json"`
-- `role=button label="Search"`
-- `role=menu-item label="Rename"`
+- 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.
 
-Prefer exact labels when the desktop UI is stable. Use `id=...` when the AX identifier is clearly app-owned and not a framework-generated `_NS:*` value.
+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
+Things not to rely on:
 
-- Mobile-only helpers like `install`, `reinstall`, `push`, `logs`, `network`, or generic `alert`
-- Long-press as a substitute for right-click
-- Raw coordinate assumptions across runs; macOS windows can move
-- Framework-generated `_NS:*` identifiers as stable selectors
+- Mobile-only helpers such as `install`, `reinstall`, or `push`.
+- Desktop-global click or fill parity from `desktop` or `menubar` sessions.
+- Raw coordinate assumptions across runs.
 
-## Troubleshooting
+Troubleshooting:
 
-- If visible window content is missing from `snapshot -i`, re-snapshot once after the UI settles.
-- If the wrong menu opened or no menu appeared, retry secondary-clicking the row/cell wrapper instead of the nested text node.
-- If the app has multiple windows, ensure the correct one is frontmost before relying on refs.
+- 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, make the app frontmost first and retry.
+- 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.

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

@@ -1,56 +1,69 @@
-# Remote Tenancy and Lease Admission
+# Remote Tenancy
 
-Use this reference for remote daemon HTTP flows that require explicit
-tenant/run admission control.
+## When to open this file
 
-## Transport prerequisites
+Open this file for remote daemon HTTP flows, including `--remote-config` launches, 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, lease allocation, and tenant-scoped command admission.
 
-- Start daemon in HTTP mode (`AGENT_DEVICE_DAEMON_SERVER_MODE=http|dual`).
-- Point remote clients at the host with `AGENT_DEVICE_DAEMON_BASE_URL=http(s)://host:port[/base-path]`
-  or `--daemon-base-url <url>` so the CLI skips local daemon discovery/startup.
-- Use `AGENT_DEVICE_DAEMON_AUTH_TOKEN` / `--daemon-auth-token` when the client should send the
-  shared daemon token automatically.
-- Direct JSON-RPC callers can use a token in params, `Authorization: Bearer <token>`, or
-  `x-agent-device-token`.
-- Prefer an auth hook (`AGENT_DEVICE_HTTP_AUTH_HOOK`) for caller validation and
-  tenant injection.
+## Main commands to reach for first
 
-## Lease lifecycle (JSON-RPC)
+- `agent-device open <app> --remote-config <path> --relaunch`
+- `AGENT_DEVICE_DAEMON_BASE_URL=...`
+- `AGENT_DEVICE_DAEMON_AUTH_TOKEN=...`
+- `curl ... agent_device.lease.allocate`
+- `curl ... agent_device.lease.heartbeat`
+- `curl ... agent_device.lease.release`
+- `agent-device --tenant ... --session-isolation tenant --run-id ... --lease-id ...`
 
-Use `POST /rpc` with JSON-RPC 2.0 methods:
+## Most common mistake to avoid
 
-- `agent_device.lease.allocate`
-- `agent_device.lease.heartbeat`
-- `agent_device.lease.release`
+Do not run a tenant-isolated command without matching `tenant`, `run`, and `lease` scope. Admission checks require all three to line up.
+
+## Preferred remote launch path
+
+Use this when the agent needs the simplest remote control flow: a Linux sandbox agent talks over HTTP to `agent-device` on a remote macOS host and launches the target app through a checked-in `--remote-config` profile.
+
+```bash
+agent-device open com.example.myapp --remote-config ./agent-device.remote.json --relaunch
+```
 
-Example allocate:
+- This is the preferred remote launch path for sandbox or cloud agents.
+- For Android React Native relaunch flows, install or reinstall the APK first, then relaunch by installed package name.
+- Do not use `open <apk|aab> --relaunch`; remote runtime hints are applied through the installed app sandbox.
+
+## Lease flow example
 
 ```bash
+export AGENT_DEVICE_DAEMON_BASE_URL=http://mac-host.example:4310
+export AGENT_DEVICE_DAEMON_AUTH_TOKEN=<token>
+
 curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"alloc-1","method":"agent_device.lease.allocate","params":{"tenantId":"acme","runId":"run-123","ttlMs":60000}}'
+
+agent-device \
+  --tenant acme \
+  --session-isolation tenant \
+  --run-id run-123 \
+  --lease-id <lease-id> \
+  session list --json
 ```
 
-Example heartbeat:
+Heartbeat and release example:
 
 ```bash
 curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"hb-1","method":"agent_device.lease.heartbeat","params":{"leaseId":"<lease-id>","ttlMs":60000}}'
-```
-
-Example release:
 
-```bash
 curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"rel-1","method":"agent_device.lease.release","params":{"leaseId":"<lease-id>"}}'
 ```
 
-Example session-locked command request:
+Session-locked RPC command example:
 
 ```bash
 curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
@@ -59,11 +72,34 @@ curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -d '{"jsonrpc":"2.0","id":"cmd-1","method":"agent_device.command","params":{"session":"qa-ios","command":"snapshot","positionals":[],"meta":{"lockPolicy":"reject","lockPlatform":"ios","tenantId":"acme","runId":"run-123","leaseId":"<lease-id>"}}}'
 ```
 
-Direct RPC callers can send the same session lock concept as the CLI and typed client through `meta.lockPolicy` and optional `meta.lockPlatform`.
+## Transport prerequisites
+
+- Start the daemon in HTTP mode with `AGENT_DEVICE_DAEMON_SERVER_MODE=http|dual`.
+- Point the client at the remote host with `AGENT_DEVICE_DAEMON_BASE_URL=http(s)://host:port[/base-path]`.
+- Use `AGENT_DEVICE_DAEMON_AUTH_TOKEN` or `--daemon-auth-token` when the client should send the shared daemon token automatically.
+- Direct JSON-RPC callers can authenticate with request params, `Authorization: Bearer <token>`, or `x-agent-device-token`.
+- Prefer an auth hook such as `AGENT_DEVICE_HTTP_AUTH_HOOK` when the host needs caller validation or tenant injection.
+
+## Lease lifecycle
+
+Use JSON-RPC methods on `POST /rpc`:
+
+- `agent_device.lease.allocate`
+- `agent_device.lease.heartbeat`
+- `agent_device.lease.release`
+
+Keep the lease alive for the duration of the run and release it when the tenant-scoped work is complete.
+
+Host-level lease knobs:
+
+- `AGENT_DEVICE_MAX_SIMULATOR_LEASES`
+- `AGENT_DEVICE_LEASE_TTL_MS`
+- `AGENT_DEVICE_LEASE_MIN_TTL_MS`
+- `AGENT_DEVICE_LEASE_MAX_TTL_MS`
 
 ## Command admission contract
 
-For tenant-isolated command execution, pass all four flags:
+For tenant-isolated command execution, pass all four CLI flags together:
 
 ```bash
 agent-device \
@@ -74,25 +110,11 @@ agent-device \
   session list --json
 ```
 
-Admission checks require tenant/run/lease scope alignment.
-
-The CLI sends `AGENT_DEVICE_DAEMON_AUTH_TOKEN` in both the JSON-RPC request token field and HTTP
-auth headers so existing daemon auth paths continue to work.
-
-## Failure semantics
-
-- Missing tenant/run/lease fields in tenant isolation mode: `INVALID_ARGS`
-- Lease not active or wrong scope: `UNAUTHORIZED`
-- Method mismatch: JSON-RPC `-32601` (HTTP 404)
+The CLI sends `AGENT_DEVICE_DAEMON_AUTH_TOKEN` in both the JSON-RPC request token field and HTTP auth headers so existing daemon auth paths continue to work.
 
-## Operational guidance
+## Failure semantics and trust notes
 
-- Keep TTL short and heartbeat only while a run is active.
-- Release lease immediately on run completion/error paths.
-- For remote debug sessions, inspect logs on the remote host; client-side `--debug` no longer tails
-  a local daemon log when `AGENT_DEVICE_DAEMON_BASE_URL` is set.
-- For bounded hosts, configure:
-  - `AGENT_DEVICE_MAX_SIMULATOR_LEASES`
-  - `AGENT_DEVICE_LEASE_TTL_MS`
-  - `AGENT_DEVICE_LEASE_MIN_TTL_MS`
-  - `AGENT_DEVICE_LEASE_MAX_TTL_MS`
+- 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.
+- Treat daemon auth tokens and lease identifiers as sensitive operational data.