revyl-cloud-agent git:20260729.c3a0d74A

Immutable. This exact content never changes and is served at /api/v1/blob/43b93bef7c3e40a9.

---
name: revyl-cloud-agent
description: Revyl conventions for Cursor Cloud/background agents - headless VM rules, remote builds, artifact evidence, session cleanup, and PR flow.
---

# Revyl Cloud Agent Skill

Use this skill whenever you are running as a Cursor Cloud/background agent (headless Linux VM) and working with Revyl. It layers cloud-agent-specific rules on top of `revyl-mcp-dev-loop`; load both.

## Environment Ground Rules (non-negotiable)

- The VM is headless and non-interactive. Prefer the Revyl MCP tools; never
  start the `revyl dev` TUI.
- Browser login is impossible. Call `start_dev_loop` first; if it returns
  `cloud_secret_required`, tell the user to add `remediation.env_name` as a
  Runtime Secret and start a new Cloud session. Never request or accept the key
  in chat, and do not retry when `restart_required` is true.
- If `start_dev_loop` returns `project_not_initialized`, run its exact
  remediation command once in the returned working directory, then retry once.
- **The VM has no Xcode.** Native iOS dev loops must call
  `start_dev_loop(remote=true, seed_latest=true)`. Treat Android the same
  unless the VM demonstrably has the SDK.

## Session Lifecycle (devices cost money and outlive the VM)

- Cloud device sessions do not die when the VM exits. `stop_dev_loop` (or
  `device_session(action="stop")`) is mandatory before completion.
- At the start of a run, use `device_session(action="list")` to check for a
  suitable existing session. Do not stack new devices on stale ones.

## Session Heartbeat (idle auto-stop is real)

- Reading files and waiting do not count as device activity. During long
  non-device work, call `get_dev_status` or `screenshot` periodically.
- If a session drops, inspect `get_dev_status` once, then start a fresh session
  and re-drive in one pass. One passed validation plus one screenshot is
  sufficient evidence.

## Bounded Monitoring (never hang the shell)

- Use `get_dev_status` for independent status snapshots.
- After native changes, call `rebuild`, continue independent work, then call
  `wait_for_rebuild` with the returned handle and a finite timeout.

## Artifacts and Evidence

- Post `viewer_url` as a clickable link as soon as `start_dev_loop` returns.
- The inline Revyl app may offer **Open live device**, which asks the Cursor host to open that URL after a user click. Keep the visible link as the guaranteed fallback when app UI or host navigation is unavailable.
- Use MCP `screenshot` and `device_validation` results as inline evidence.
- Never claim the Cloud VM opened a browser or the user's local Cursor Desktop. Automatic Cloud-to-client navigation requires a Cursor host capability; shell browser commands target only the VM.

## Auth Bypass and Secrets

- If the app shows a logged-out state mid-session but the boot token is still valid, run `revyl dev auth refresh --json` (re-fires the boot deep link; does not remint). If the token itself expired, `revyl dev stop` then `revyl dev` so a fresh mint is applied as launch environment.
- Never paste launch-var values, tokens, or API keys into code, chat, logs, screenshots, or PRs — reference variable names only. Avoid typing real credentials on-screen; use test variables.

## Git Hygiene

- Before committing, confirm `.revyl/.gitignore` exists (created by `revyl init`; it keeps dev-session runtime state out of git — only `config.yaml` and `tests/` belong in the repo).
- Never commit artifacts, screenshots, logs, or minted launch-var files.

## PR Flow

- If `gh` is read-only in this environment, use the ManagePullRequest tool instead.
- The PR body carries the evidence: the `viewer_url`, the key inline screenshots, and a one-line summary of what was verified on-device.