@desplega.ai/qa-use 2.17.0 → 2.19.0

package/dist/src/cli/generated/docs-content.d.ts

@@ -3,7 +3,7 @@
  * DO NOT EDIT MANUALLY — Generated from plugins/qa-use/skills/qa-use/
  * Run 'bun run generate:docs' to regenerate.
  */
-export declare const MAIN_DOC = "---\nname: qa-use\ndescription: E2E testing and browser automation with qa-use CLI. Use when the user needs to run tests, verify features, automate browser interactions, or debug test failures.\nallowed-tools: Bash(qa-use *)\n---\n\n# qa-use\n\nE2E testing and browser automation for AI-driven development workflows.\n\n## Critical Insight: Plugin Commands as Shortcuts\n\n**For AI Harnesses (codex, opencode, etc.):**\n\nPlugin commands (slash commands like `/qa-use:verify`) are **convenience shortcuts** that wrap CLI workflows. Harnesses with only the Bash tool can access ALL functionality via CLI commands documented below.\n\n**Pattern throughout this document:**\n- **CLI Workflow**: Step-by-step CLI commands (works for ALL harnesses)\n- **Plugin Shortcut**: Optional slash command (convenience)\n\n## Setup & Configuration\n\nBefore using any qa-use commands, verify configuration is in place:\n\n```bash\n# Check current configuration (no-op if already configured)\nqa-use setup\n\n# Configure with API key (validates against server)\nqa-use setup --api-key <key>\n\n# View full configuration details\nqa-use info\n```\n\n**Environment Variables (alternative to config file):**\n\n| Variable | Description |\n|----------|-------------|\n| `QA_USE_API_KEY` | API key for authentication |\n| `QA_USE_REGION` | Region: `us` (default) or `auto` |\n| `QA_USE_API_URL` | Override API base URL |\n\n**Config file:** `.qa-use.json` in the project directory or `~/.qa-use.json` in the home directory. Precedence: env vars > project `.qa-use.json` > `~/.qa-use.json`.\n\n**If you encounter \"API key not configured\", 401, or auth errors:** Run `qa-use setup` to check config state. NEVER fabricate or guess API keys.\n\n## Core Workflow\n\n### 1. Browser Control & Session Lifecycle\n\n**CLI Workflow:**\n```bash\n# Create browser session (returns immediately \u2014 runs detached in the background)\nqa-use browser create --viewport desktop\n\n# For localhost testing \u2014 auto-tunnels when base URL is localhost and API is remote.\n# No flag needed for the common case:\nqa-use browser create --no-headless http://localhost:3000\n\n# Force a tunnel even in dev mode:\nqa-use browser create --tunnel on --no-headless\n\n# Opt out of auto-tunnel (e.g. backend is also local):\nqa-use browser create --no-tunnel\n\n# Navigate\nqa-use browser goto https://example.com\n\n# Snapshot to get element refs (ALWAYS do this before interacting)\nqa-use browser snapshot\n\n# Interact by ref\nqa-use browser click e3\nqa-use browser fill e5 \"text\"\n\n# Close\nqa-use browser close\n```\n\n**Background session management:**\n\n`qa-use browser create` returns immediately \u2014 the actual browser + tunnel run in a detached child process so your terminal stays free. Manage sessions with:\n\n```bash\nqa-use browser status --list   # Show all active sessions across processes\nqa-use browser status           # Details for the auto-resolved session\nqa-use browser close <id>       # Close a specific session\nqa-use doctor                   # Reap stale sessions/tunnels (dead PIDs)\nqa-use doctor --dry-run         # Preview what would be cleaned\n```\n\n**Tunnel commands:**\n\nCross-process tunnel registry \u2014 multiple commands share a single tunnel per target:\n\n```bash\nqa-use tunnel start <url>         # Acquire a tunnel (released immediately unless --hold)\nqa-use tunnel start <url> --hold  # Keep the tunnel up until Ctrl+C\nqa-use tunnel ls                  # List active tunnels (target, public URL, refcount)\nqa-use tunnel status <target>     # Detail for a single tunnel\nqa-use tunnel close <target>      # Force-release a tunnel (kills detached holders)\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:explore https://example.com\n```\n(Wraps create + goto + snapshot with autonomous exploration)\n\n**Critical:** Always run `snapshot` before your **first** interaction on a page. Never guess element refs.\n\n**Snapshot Diff Feature (use it to avoid unnecessary snapshots):**\nAfter each action (goto, click, fill, etc.), the browser automatically shows DOM changes:\n- **Summary**: \"5 elements added, 1 element modified\"\n- **Added elements**: `+ [e54] generic \"Thanks for agreeing!\"` (green)\n- **Modified elements**: `~ [e18] checkbox \"I agree...\"` with `+attrs: checked, active` (yellow)\n- **Removed elements**: `- [e99] button \"Submit\"` (red)\n\n**When you can skip a full `snapshot`:** If the diff output from your last action already shows the element ref you need to interact with next, use it directly \u2014 no need for an intermediate `snapshot`. For example, if clicking a button shows `+ [e54] button \"Submit\"` in the diff, you can `click e54` immediately.\n\n**When you still need a full `snapshot`:** Run `snapshot` when you need to find elements that weren't in the diff (e.g., pre-existing elements you haven't interacted with yet), or when the diff was truncated (shows \"... and N more changes\").\n\n### 2. Understanding Blocks\n\n**What are blocks?**\n\nBlocks are atomic recorded interactions from a browser session. They are:\n- Automatically captured during any browser interaction (click, fill, goto, scroll, etc.)\n- Stored server-side with the session\n- Retrieved via `qa-use browser get-blocks`\n- The foundation for test generation\n\n**Why blocks matter:**\n- **Record-once, replay-many**: Interactive recording becomes automated test\n- **AI-friendly**: Agents can analyze blocks to understand user intent\n- **Version control**: Blocks stored with session enable test iteration\n- **Bridge CLI \u2192 Tests**: Natural workflow from exploration to automation\n\n**How blocks work:**\n\n```bash\n# 1. Create session and interact (auto-tunnels localhost)\nqa-use browser create --no-headless\nqa-use browser goto https://example.com\nqa-use browser snapshot        # Returns: [ref=e1] button\nqa-use browser click e1        # Records as block\nqa-use browser fill e5 \"text\"  # Records as block\n\n# 2. Retrieve blocks (JSON array)\nqa-use browser get-blocks\n# Returns:\n# [\n#   {\"type\": \"goto\", \"url\": \"...\", \"timestamp\": \"...\"},\n#   {\"type\": \"click\", \"ref\": \"e1\", \"timestamp\": \"...\"},\n#   {\"type\": \"fill\", \"ref\": \"e5\", \"value\": \"text\", \"timestamp\": \"...\"}\n# ]\n\n# 3. Generate test YAML from blocks\nqa-use browser generate-test -n \"my_test\" -o qa-tests/my_test.yaml\n\n# 4. Run generated test\nqa-use test run my_test\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record start my_test\n# ... perform interactions ...\n/qa-use:record stop\n```\n(Wraps the interactive workflow with AI-powered test generation)\n\n### 3. Test Management\n\n**CLI Workflow:**\n```bash\n# Run test by name\nqa-use test run login\n\n# Run and save the (non-synced) local test to cloud\nqa-use test run login --persist\n\n# Validate syntax\nqa-use test validate login\n\n# Show test details\nqa-use test info login\n\n# List test runs\nqa-use test runs --status failed\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:test-run login\n```\n(Convenience shortcut for common test execution)\n\n### 4. Test Variables (Imperative Edit)\n\nQuick `set`/`unset` for the typed `variables:` block on a single test \u2014\nuseful when you don't want to round-trip the full YAML.\n\n**CLI Workflow:**\n```bash\n# Local YAML file \u2014 Document API preserves comments + key order\nqa-use test vars list  qa-tests/login.yaml\nqa-use test vars list  qa-tests/login.yaml --json\nqa-use test vars set   qa-tests/login.yaml --key user --value alice\nqa-use test vars set   qa-tests/login.yaml --key url --value https://x \\\n                                          --type url --lifetime all\nqa-use test vars set   qa-tests/login.yaml --key password --value hunter2 --sensitive\nqa-use test vars set   qa-tests/login.yaml --key password --sensitive  # preserves stored value\nqa-use test vars unset qa-tests/login.yaml --key user\n\n# Remote --id fallback \u2014 exports YAML, mutates, re-imports (best-effort RMW)\nqa-use test vars list  --id <uuid>\nqa-use test vars set   --id <uuid> --key user --value alice\nqa-use test vars unset --id <uuid> --key user\n```\n\n**Rules:**\n\n- **Mutual exclusion**: pass either `<file>` *or* `--id`, not both. Neither \u2192 exit 1.\n- **`--id` requires a full UUID** (use `qa-use test list --query <name>` to find one).\n- **Form upgrade**: passing only `--key`/`--value` writes simple form (`key: value`).\n  Any of `--type`/`--lifetime`/`--context`/`--sensitive` upgrades to full form\n  (`{ value, type, lifetime, context, is_sensitive }`).\n- **Sensitive-preserve**: on an existing sensitive var, `--sensitive` *without*\n  `--value` keeps the stored value. On a new key, that combination errors out.\n- **`--json` redaction**: sensitive entries omit the `value` key entirely; the\n  `is_sensitive: true` flag is the redaction signal.\n- **Remote round-trip caveat**: comment/key-order preservation only applies to\n  the local-file path. The server normalizes formatting on import.\n\n**No Plugin Shortcut** - Use CLI commands directly.\n\n### 5. Test Sync Lifecycle\n\n**CLI Workflow:**\n```bash\n# Pull tests from cloud\nqa-use test sync pull\n\n# Push all local tests to cloud\nqa-use test sync push --all\n\n# Push specific test\nqa-use test sync push --id <uuid>\n\n# Force push (overwrite conflicts)\nqa-use test sync push --force\n\n# Compare local vs cloud\nqa-use test diff login.yaml\n```\n\n**Persist vs Sync:**\n\nA local test is **synced** when its YAML has both an `id:` and a `version_hash:`\n(these are written back by `test sync push`/`pull`). `--persist` on `test run`\nand `qa-use test sync` are related but not the same:\n\n| Local file state | `persist` | What happens at run time |\n|---|---|---|\n| Non-synced | `false` (default) | Runs locally; nothing saved to cloud. Re-run with `--persist` or use `test sync push` to persist. |\n| Non-synced | `true` | Test is uploaded as a **new** cloud entry after the run. Re-running like this creates **duplicates** \u2014 prefer `test sync push` once the file tracks the cloud id. |\n| Synced | `false` | Runs against the cloud-tracked definition; no extra write. |\n| Synced | `true` | Cloud definition is **upserted** (may overwrite newer cloud edits). Use `test sync push`/`pull` for explicit version control. |\n\nRule of thumb: `test sync push`/`pull` is the deliberate path. Reserve `--persist`\n(or `defaults.persist: true` in `.qa-use.json`) for one-off uploads of brand-new\nlocal tests.\n\n**No Plugin Shortcut** - Use CLI commands directly\n\n## Essential Commands\n\n### Browser Session Management\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser create` | Create remote browser session |\n| `qa-use browser create <url>` | Create session and navigate to URL |\n| `qa-use browser create --tunnel [auto\\|on\\|off]` | Tunnel mode \u2014 default `auto` (localhost + remote API). `--no-tunnel` is sugar for `off`. |\n| `qa-use browser create --no-headless` | Show browser window (paired with a local/tunnel browser) |\n| `qa-use browser create --viewport <size>` | Set viewport: `desktop`, `tablet`, `mobile` |\n| `qa-use browser create --ws-url <url>` | Connect to existing WebSocket browser |\n| `qa-use browser create --after-test-id <uuid>` | Run a test first, then become interactive |\n| `qa-use browser create --var <key=value>` | Override app config variables (repeatable) |\n| `qa-use browser list` | List active sessions |\n| `qa-use browser status` | Show current session details (app_url, recording_url, etc.) |\n| `qa-use browser status --list` | Show all active sessions across processes |\n| `qa-use browser close` | Close active session |\n| `qa-use browser close <id>` | Close a specific session by id |\n| `qa-use doctor` | Reap stale sessions/tunnels (dead PIDs) |\n| `qa-use tunnel ls` | List active tunnels in the registry |\n| `qa-use tunnel start <url> --hold` | Hold a public tunnel for external consumers |\n\nSessions auto-persist in `~/.qa-use.json`. One active session = no `-s` flag needed. `browser create` returns immediately \u2014 the browser + tunnel run in a detached child. Use `qa-use doctor` if stale state accumulates.\n\n### Navigation\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser goto <url>` | Navigate to URL |\n| `qa-use browser back` | Go back |\n| `qa-use browser forward` | Go forward |\n| `qa-use browser reload` | Reload page |\n\n### Element Interaction\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser click <ref>` | Click element by ref |\n| `qa-use browser click --text \"Button\"` | Click by semantic description |\n| `qa-use browser fill <ref> \"value\"` | Fill input field |\n| `qa-use browser type <ref> \"text\"` | Type with delays (for autocomplete) |\n| `qa-use browser press <key>` | Press key (e.g., `Enter`, `Tab`) |\n| `qa-use browser check <ref>` | Check checkbox |\n| `qa-use browser uncheck <ref>` | Uncheck checkbox |\n| `qa-use browser select <ref> \"option\"` | Select dropdown option |\n| `qa-use browser hover <ref>` | Hover over element |\n| `qa-use browser scroll down 500` | Scroll by pixels |\n| `qa-use browser scroll-into-view <ref>` | Scroll element into view |\n| `qa-use browser drag <ref> --target <ref>` | Drag element to target |\n| `qa-use browser mfa-totp [ref] <secret>` | Generate TOTP code (optionally fill) |\n| `qa-use browser upload <ref> <file>...` | Upload file(s) to input (base64-encoded, works remote & tunnel) |\n\n### Inspection & Snapshot Diff\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser snapshot` | Get full ARIA tree with element refs (use only when diff output is insufficient) |\n| `qa-use browser url` | Get current URL |\n| `qa-use browser screenshot` | Save screenshot.png |\n| `qa-use browser screenshot file.png` | Save to custom path |\n| `qa-use browser screenshot --base64` | Output base64 to stdout |\n| `qa-use browser evaluate <expression>` | Execute JavaScript in browser context |\n\nThe snapshot-diff feature automatically displays DOM changes after each browser action:\n- **Added elements**: Shown with `+` prefix and green color \u2014 these refs are immediately usable\n- **Modified elements**: Shown with `~` prefix and yellow color, including attribute changes (`+attrs: checked`)\n- **Removed elements**: Shown with `-` prefix and red color \u2014 do NOT use these refs\n\n**Downloads:** When an action triggers a file download (e.g., clicking a download link), the response includes download info: filename, size, and a presigned URL. Use `qa-use browser downloads` to list all downloads or `--save <dir>` to save them locally.\n\nUse diff output to interact with newly appeared elements directly, without running a full `snapshot` first.\n\n### Test Operations\n\n| Command | Description |\n|---------|-------------|\n| `qa-use test run <name>` | Run test by name |\n| `qa-use test run --all` | Run all tests |\n| `qa-use test run <name> --tunnel [mode]` | Override tunnel mode (`auto`, `on`, `off`). `--no-tunnel` is sugar for `off`. Bare `--tunnel` is sugar for `on`. |\n| `qa-use test run <name> --download` | Download assets to `/tmp/qa-use/downloads/` |\n| `qa-use test run <name> --var key=value` | Override variable |\n| `qa-use test validate <name>` | Validate test syntax |\n| `qa-use test list` | List available tests |\n| `qa-use test info <name>` | Show test details (steps, tags, description) |\n| `qa-use test info --id <uuid>` | Show cloud test details by ID |\n| `qa-use test runs [name]` | List test run history |\n| `qa-use test runs --id <uuid>` | Filter runs by test ID |\n| `qa-use test runs --status failed` | Filter runs by status |\n| `qa-use test init` | Initialize test directory |\n| `qa-use test sync pull` | Pull tests from cloud |\n| `qa-use test sync push --all` | Push all local tests to cloud |\n| `qa-use test sync push --id <uuid>` | Push specific test |\n| `qa-use test sync push --force` | Push tests, overwriting conflicts |\n| `qa-use test diff <file>` | Compare local vs cloud test |\n| `qa-use test schema [path]` | View test definition schema |\n\n### API Operations (Dynamic OpenAPI)\n\n`qa-use api` dynamically discovers operations from `/api/v1/openapi.json` and caches metadata locally for offline fallback.\n\n| Command | Description |\n|---------|-------------|\n| `qa-use api` | Show help and available subcommands |\n| `qa-use api ls` | List available `/api/v1/*` routes from OpenAPI |\n| `qa-use api ls --refresh` | Force refresh OpenAPI cache |\n| `qa-use api ls --offline` | Use cached OpenAPI metadata only |\n| `qa-use api info /api/v1/<route>` | Show route details: parameters, request body, responses |\n| `qa-use api info /api/v1/<route> -X POST` | Show info for specific HTTP method |\n| `qa-use api info /api/v1/<route> --json` | Route info as JSON |\n| `qa-use api examples` | Show usage examples |\n| `qa-use api openapi` | Print OpenAPI spec URL |\n| `qa-use api openapi --raw` | Dump full OpenAPI spec as JSON |\n| `qa-use api /api/v1/tests` | Call endpoint (method inferred when possible) |\n| `qa-use api -X GET /api/v1/test-runs -f limit=5` | GET with query fields |\n| `qa-use api -X POST /api/v1/tests-actions/run --input body.json` | POST with JSON body file |\n| `qa-use api -X GET /api/v1/test-runs/<id>` | Fetch detail endpoint by ID |\n\n**No Plugin Shortcut** - Use CLI commands directly.\n\n### Logs & Debugging\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser logs console` | View console logs from session |\n| `qa-use browser logs console -s <id>` | View logs from specific/closed session |\n| `qa-use browser logs network` | View network request logs |\n| `qa-use browser logs network -s <id>` | View network logs from specific session |\n| `qa-use browser downloads` | List downloaded files from session |\n| `qa-use browser downloads --save <dir>` | Save downloaded files to local directory |\n| `qa-use browser downloads --json` | Output download info as JSON |\n\n### Test Generation\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser generate-test` | Generate test YAML from recorded session |\n| `qa-use browser generate-test -s <id>` | Generate from specific session |\n| `qa-use browser generate-test -n <name>` | Specify test name |\n| `qa-use browser generate-test -o <path>` | Specify output path |\n| `qa-use browser get-blocks` | Get recorded interaction blocks (JSON) |\n\n### Waiting\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser wait <ms>` | Fixed wait |\n| `qa-use browser wait-for-selector \".class\"` | Wait for selector |\n| `qa-use browser wait-for-load` | Wait for page load |\n\n### Variable Overrides\n\nUse `--var` to override app config variables at runtime. Common variables:\n\n| Variable | Description |\n|----------|-------------|\n| `base_url` | Base URL for the app (e.g., preview deployment URL) |\n| `login_url` | Login page URL |\n| `login_username` | Username/email for authentication |\n| `login_password` | Password for authentication |\n\nExample with ephemeral preview URL:\n```bash\nqa-use browser create --after-test-id <login-test-uuid> \\\n  --var base_url=https://preview-123.example.com \\\n  --var login_url=https://preview-123.example.com/auth/login\n```\n\n## Common Patterns\n\n### Pattern 1: Feature Verification\n\n**CLI Workflow:**\n```bash\n# 1. Search for existing test\nqa-use test list | grep \"login\"\n\n# 2. Run test\nqa-use test run login\n\n# 3. Debug failures\nqa-use browser logs console\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:verify \"login works with valid credentials\"\n```\n(Wraps the above CLI workflow with AI-powered test discovery and analysis)\n\n### Pattern 2: Record & Generate Test\n\n**CLI Workflow:**\n```bash\n# 1. Create session (auto-tunnels localhost targets)\nqa-use browser create --no-headless\n\n# 2. Navigate and interact\nqa-use browser goto https://example.com\nqa-use browser snapshot\nqa-use browser click e1\nqa-use browser fill e5 \"test\"\n\n# 3. Generate test from blocks\nqa-use browser get-blocks\nqa-use browser generate-test -n \"my_test\"\n\n# 4. Run test\nqa-use test run my_test\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record start my_test\n# ... perform interactions ...\n/qa-use:record stop\n```\n\n### Pattern 3: Authenticated Exploration\n\n**CLI Workflow:**\n```bash\n# Create session that runs login test first\nqa-use browser create --after-test-id <login-test-uuid>\n\n# Session now authenticated, explore\nqa-use browser goto /dashboard\nqa-use browser snapshot\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:explore /dashboard\n```\n(Automatically handles auth detection and session creation)\n\n### Pattern 4: Edit Existing Test\n\n**CLI Workflow:**\n```bash\n# 1. Open test file in editor\nvim qa-tests/login.yaml\n\n# 2. Validate syntax\nqa-use test validate login\n\n# 3. Run to verify\nqa-use test run login\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record edit login\n```\n(AI-assisted editing with validation)\n\n### Pattern 5: Using Snapshot Diff to Avoid Unnecessary Snapshots\n\n**CLI Workflow:**\n```bash\n# Create session and navigate\nqa-use browser create --no-headless\nqa-use browser goto https://evals.desplega.ai/checkboxes\n\n# goto shows diff \u2014 initial page load shows all elements:\n# Changes: 45 elements added\n# + [e18] checkbox \"I agree to the terms and conditions\"\n# + [e19] generic \"I agree to the terms and conditions\"\n\n# \u2705 Use ref from diff directly \u2014 no snapshot needed!\nqa-use browser click e18\n\n# Diff shows what changed:\n# Changes: 5 elements added, 1 element modified\n# + [e54] generic \"Thanks for agreeing!\"\n# + [e55] link \"Terms and Conditions\"\n# ~ [e18] checkbox \"I agree to the terms and conditions\"\n#     +attrs: active, checked\n\n# \u2705 Can click e55 directly from diff output \u2014 no snapshot needed!\nqa-use browser click e55\n\n# \u274C Need to find an element NOT in the diff? Now run snapshot:\nqa-use browser snapshot\n```\n\n**Key principle:** Use diff output as your primary source of element refs after actions. Only fall back to `snapshot` when you need to find elements that weren't in the diff.\n\n**Benefits:**\n- Fewer API calls = faster automation\n- Diff refs are always fresh (just returned from the server)\n- Instantly see what changed (new elements, attribute changes, removals)\n\n**No Plugin Shortcut** - Automatic feature in all browser commands\n\n## CI/CD Integration\n\n### Running Tests in CI\n\n**Environment Variables:**\n```bash\nexport QA_USE_API_KEY=\"your-api-key\"\nexport QA_USE_REGION=\"us\"  # Optional: \"us\" or \"auto\"\n```\n\n**Basic Test Execution:**\n```bash\n# Run all tests\nqa-use test run --all\n\n# Run specific tag\nqa-use test run --tag smoke\n\n# Exit codes: 0 = pass, 1 = fail\n```\n\n### GitHub Actions Example\n\n```yaml\nname: QA Tests\non: [push, pull_request]\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-node@v3\n        with:\n          node-version: '20'\n      - name: Install qa-use\n        run: npm install -g @desplega.ai/qa-use\n      - name: Run tests\n        run: qa-use test run --all\n        env:\n          QA_USE_API_KEY: ${{ secrets.QA_USE_API_KEY }}\n```\n\n### Test Artifacts\n\n**Screenshots:**\n- Automatically saved on failure\n- Location: `/tmp/qa-use/downloads/` (local) or cloud (remote)\n\n**Logs:**\n- Console logs: `qa-use browser logs console -s <session-id>`\n- Network logs: `qa-use browser logs network -s <session-id>`\n\n## Advanced Topics\n\n### Localhost Testing (Auto-Tunnel)\n\n**qa-use auto-tunnels localhost targets when the API is remote.** No flag required for the common case:\n\n```bash\nqa-use browser create --no-headless http://localhost:3000\nqa-use test run my_test   # auto-tunnels if base_url is localhost\n```\n\n**Tri-state `--tunnel` flag:**\n\n| Value | Behavior |\n|-------|----------|\n| `auto` (default) | Tunnel iff base URL is localhost AND API URL is remote |\n| `on` (or bare `--tunnel`) | Force a tunnel even in dev mode |\n| `off` (or `--no-tunnel`) | Never tunnel |\n\n```\nTesting localhost (http://localhost:3000)?\n  \u251C\u2500 API remote (default)  \u2192 auto-tunnels. No flag needed.\n  \u251C\u2500 API also local (dev)  \u2192 no tunnel by default. Use --tunnel on to force.\n  \u2514\u2500 Public URL target     \u2192 no tunnel (remote cloud browser)\n```\n\n**Plugin shortcuts handle tunnel detection automatically:**\n```\n/qa-use:explore http://localhost:3000\n/qa-use:record start local_test\n```\n\nSee [references/localhost-testing.md](references/localhost-testing.md) for troubleshooting.\n\n### Session Persistence\n\nSessions are stored in `~/.qa-use.json` and have:\n- **TTL**: 30 minutes (default)\n- **Auto-resolve**: One active session = no `-s` flag needed\n- **Cleanup**: Automatic on timeout or explicit `browser close`\n\n### Block Limitations\n\n**What's captured:**\n- goto, click, fill, type, check, uncheck, select, hover\n- scroll, scroll-into-view, drag, upload, press\n\n**What's NOT captured:**\n- Assertions (must be added manually)\n- Waits (inferred from timing, may need adjustment)\n- Complex interactions (multi-drag, hover sequences)\n\n**Manual editing:** Edit generated YAML to add assertions and refine selectors.\n\n### WebSocket Sessions\n\n**Sharing sessions across processes:**\n```bash\n# Process 1: Create session (auto-tunnels if target is localhost + API remote)\nqa-use browser create http://localhost:3000\n# Output: ws://localhost:12345/browser/abc123\n\n# Process 2: Connect to session\nqa-use browser goto https://example.com --ws-url ws://localhost:12345/browser/abc123\n```\n\n## Deep-Dive References\n\nAccess any reference at runtime via the CLI: `qa-use docs <topic>`\n\n| Topic | CLI Command | Description |\n|-------|-------------|-------------|\n| [browser-commands.md](references/browser-commands.md) | `qa-use docs browser-commands` | Complete browser CLI reference with all flags |\n| [test-format.md](references/test-format.md) | `qa-use docs test-format` | Full test YAML specification |\n| [localhost-testing.md](references/localhost-testing.md) | `qa-use docs localhost-testing` | Tunnel setup for local development |\n| [failure-debugging.md](references/failure-debugging.md) | `qa-use docs failure-debugging` | Failure classification and diagnostics |\n| [ci.md](references/ci.md) | `qa-use docs ci` | CI/CD integration patterns and examples |\n\nUse `qa-use docs --list` to discover all available topics and templates.\n\n## Templates\n\n| Template | Description |\n|----------|-------------|\n| [basic-test.yaml](templates/basic-test.yaml) | Simple navigation and assertion |\n| [auth-flow.yaml](templates/auth-flow.yaml) | Login flow with credentials |\n| [form-test.yaml](templates/form-test.yaml) | Form submission with validation |\n\n## Test Format Overview\n\n```yaml\nname: Login Test\ndescription: Validates login functionality with valid credentials\ntags:\n  - smoke\n  - auth\napp_config: <app-config-id>\nvariables:\n  email: test@example.com\n  password: secret123\ndepends_on: setup-test  # Optional\nsteps:\n  - action: goto\n    url: /login\n  - action: fill\n    target: email input\n    value: $email\n  - action: click\n    target: login button\n  - action: to_be_visible\n    target: dashboard\n```\n\nSee [references/test-format.md](references/test-format.md) for complete specification.\n\n## Common Mistakes\n\n| \u274C Wrong | \u2705 Correct |\n|---------|-----------|\n| `browser navigate <url>` | `browser goto <url>` |\n| `browser destroy` | `browser close` |\n| `browser close <session-id>` | `browser close` |\n| Guessing element refs | Use refs from diff output or `snapshot` |\n| Running `snapshot` after every action | Use diff output; only `snapshot` when needed |\n| Forcing `--tunnel` in dev (both local) | Rely on auto-mode, or use `--tunnel on` explicitly |\n| `test sync --pull` | `test sync pull` (subcommand, not flag) |\n| `test sync --push` | `test sync push` (subcommand, not flag) |\n\n## Troubleshooting\n\nWhen stuck or encountering unexpected errors, use the built-in documentation:\n\n```bash\n# Check configuration state\nqa-use setup\n\n# Browse main documentation\nqa-use docs\n\n# List all available topics\nqa-use docs --list\n\n# Access specific topic\nqa-use docs <topic>\n```\n\n| Situation | Command |\n|-----------|---------|\n| Auth / API key errors | `qa-use setup` then `qa-use docs` |\n| Unknown browser command | `qa-use docs browser-commands` |\n| Test failures | `qa-use docs failure-debugging` |\n| Localhost / tunnel issues | `qa-use docs localhost-testing` |\n| Test YAML syntax | `qa-use docs test-format` |\n| CI/CD setup | `qa-use docs ci` |\n\n**Key rules:**\n- ALWAYS consult `qa-use docs` before improvising workarounds\n- NEVER fabricate API keys, tokens, URLs, or credentials\n- If `qa-use setup` shows no config, report it \u2014 don't guess\n\n## npx Alternative\n\nAll commands use `qa-use` assuming global install. For one-off use:\n```bash\nnpx @desplega.ai/qa-use browser <command>\n```\n";
+export declare const MAIN_DOC = "---\nname: qa-use\ndescription: E2E testing and browser automation with qa-use CLI. Use when the user needs to run tests, verify features, automate browser interactions, or debug test failures.\nallowed-tools: Bash(qa-use *)\n---\n\n# qa-use\n\nE2E testing and browser automation for AI-driven development workflows.\n\n## Critical Insight: Plugin Commands as Shortcuts\n\n**For AI Harnesses (codex, opencode, etc.):**\n\nPlugin commands (slash commands like `/qa-use:verify`) are **convenience shortcuts** that wrap CLI workflows. Harnesses with only the Bash tool can access ALL functionality via CLI commands documented below.\n\n**Pattern throughout this document:**\n- **CLI Workflow**: Step-by-step CLI commands (works for ALL harnesses)\n- **Plugin Shortcut**: Optional slash command (convenience)\n\n## Setup & Configuration\n\nBefore using any qa-use commands, verify configuration is in place:\n\n```bash\n# Check current configuration (no-op if already configured)\nqa-use setup\n\n# Configure with API key (validates against server)\nqa-use setup --api-key <key>\n\n# View full configuration details\nqa-use info\n```\n\n**Environment Variables (alternative to config file):**\n\n| Variable | Description |\n|----------|-------------|\n| `QA_USE_API_KEY` | API key for authentication |\n| `QA_USE_REGION` | Region: `us` (default) or `auto` |\n| `QA_USE_API_URL` | Override API base URL |\n\n**Config file:** `.qa-use.json` in the project directory or `~/.qa-use.json` in the home directory. Precedence: env vars > project `.qa-use.json` > `~/.qa-use.json`.\n\n**If you encounter \"API key not configured\", 401, or auth errors:** Run `qa-use setup` to check config state. NEVER fabricate or guess API keys.\n\n## Core Workflow\n\n### 1. Browser Control & Session Lifecycle\n\n**CLI Workflow:**\n```bash\n# Create browser session (returns immediately \u2014 runs detached in the background)\nqa-use browser create --viewport desktop\n\n# For localhost testing \u2014 auto-tunnels when base URL is localhost and API is remote.\n# No flag needed for the common case:\nqa-use browser create --no-headless http://localhost:3000\n\n# Force a tunnel even in dev mode:\nqa-use browser create --tunnel on --no-headless\n\n# Opt out of auto-tunnel (e.g. backend is also local):\nqa-use browser create --no-tunnel\n\n# Navigate\nqa-use browser goto https://example.com\n\n# Snapshot to get element refs (ALWAYS do this before interacting)\nqa-use browser snapshot\n\n# Interact by ref\nqa-use browser click e3\nqa-use browser fill e5 \"text\"\n\n# Close\nqa-use browser close\n```\n\n**Background session management:**\n\n`qa-use browser create` returns immediately \u2014 the actual browser + tunnel run in a detached child process so your terminal stays free. Manage sessions with:\n\n```bash\nqa-use browser status --list   # Show all active sessions across processes\nqa-use browser status           # Details for the auto-resolved session\nqa-use browser close <id>       # Close a specific session\nqa-use doctor                   # Reap stale sessions/tunnels (dead PIDs)\nqa-use doctor --dry-run         # Preview what would be cleaned\n```\n\n**Tunnel commands:**\n\nCross-process tunnel registry \u2014 multiple commands share a single tunnel per target:\n\n```bash\nqa-use tunnel start <url>         # Acquire a tunnel (released immediately unless --hold)\nqa-use tunnel start <url> --hold  # Keep the tunnel up until Ctrl+C\nqa-use tunnel ls                  # List active tunnels (target, public URL, refcount)\nqa-use tunnel status <target>     # Detail for a single tunnel\nqa-use tunnel close <target>      # Force-release a tunnel (kills detached holders)\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:explore https://example.com\n```\n(Wraps create + goto + snapshot with autonomous exploration)\n\n**Critical:** Always run `snapshot` before your **first** interaction on a page. Never guess element refs.\n\n**Snapshot Diff Feature (use it to avoid unnecessary snapshots):**\nAfter each action (goto, click, fill, etc.), the browser automatically shows DOM changes:\n- **Summary**: \"5 elements added, 1 element modified\"\n- **Added elements**: `+ [e54] generic \"Thanks for agreeing!\"` (green)\n- **Modified elements**: `~ [e18] checkbox \"I agree...\"` with `+attrs: checked, active` (yellow)\n- **Removed elements**: `- [e99] button \"Submit\"` (red)\n\n**When you can skip a full `snapshot`:** If the diff output from your last action already shows the element ref you need to interact with next, use it directly \u2014 no need for an intermediate `snapshot`. For example, if clicking a button shows `+ [e54] button \"Submit\"` in the diff, you can `click e54` immediately.\n\n**When you still need a full `snapshot`:** Run `snapshot` when you need to find elements that weren't in the diff (e.g., pre-existing elements you haven't interacted with yet), or when the diff was truncated (shows \"... and N more changes\").\n\n### 2. Understanding Blocks\n\n**What are blocks?**\n\nBlocks are atomic recorded interactions from a browser session. They are:\n- Automatically captured during any browser interaction (click, fill, goto, scroll, etc.)\n- Stored server-side with the session\n- Retrieved via `qa-use browser get-blocks`\n- The foundation for test generation\n\n**Why blocks matter:**\n- **Record-once, replay-many**: Interactive recording becomes automated test\n- **AI-friendly**: Agents can analyze blocks to understand user intent\n- **Version control**: Blocks stored with session enable test iteration\n- **Bridge CLI \u2192 Tests**: Natural workflow from exploration to automation\n\n**How blocks work:**\n\n```bash\n# 1. Create session and interact (auto-tunnels localhost)\nqa-use browser create --no-headless\nqa-use browser goto https://example.com\nqa-use browser snapshot        # Returns: [ref=e1] button\nqa-use browser click e1        # Records as block\nqa-use browser fill e5 \"text\"  # Records as block\n\n# 2. Retrieve blocks (JSON array)\nqa-use browser get-blocks\n# Returns:\n# [\n#   {\"type\": \"goto\", \"url\": \"...\", \"timestamp\": \"...\"},\n#   {\"type\": \"click\", \"ref\": \"e1\", \"timestamp\": \"...\"},\n#   {\"type\": \"fill\", \"ref\": \"e5\", \"value\": \"text\", \"timestamp\": \"...\"}\n# ]\n\n# 3. Generate test YAML from blocks\nqa-use browser generate-test -n \"my_test\" -o qa-tests/my_test.yaml\n\n# 4. Run generated test\nqa-use test run my_test\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record start my_test\n# ... perform interactions ...\n/qa-use:record stop\n```\n(Wraps the interactive workflow with AI-powered test generation)\n\n### 3. Test Management\n\n**CLI Workflow:**\n```bash\n# Run test by name\nqa-use test run login\n\n# Run and save the (non-synced) local test to cloud\nqa-use test run login --persist\n\n# Validate syntax\nqa-use test validate login\n\n# Show test details\nqa-use test info login\n\n# List test runs\nqa-use test runs --status failed\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:test-run login\n```\n(Convenience shortcut for common test execution)\n\n### 4. Test Variables (Imperative Edit)\n\nQuick `set`/`unset` for the typed `variables:` block on a single test \u2014\nuseful when you don't want to round-trip the full YAML.\n\n**CLI Workflow:**\n```bash\n# Local YAML file \u2014 Document API preserves comments + key order\nqa-use test vars list  qa-tests/login.yaml\nqa-use test vars list  qa-tests/login.yaml --json\nqa-use test vars set   qa-tests/login.yaml --key user --value alice\nqa-use test vars set   qa-tests/login.yaml --key url --value https://x \\\n                                          --type url --lifetime all\nqa-use test vars set   qa-tests/login.yaml --key password --value hunter2 --sensitive\nqa-use test vars set   qa-tests/login.yaml --key password --sensitive  # preserves stored value\nqa-use test vars unset qa-tests/login.yaml --key user\n\n# Remote --id fallback \u2014 exports YAML, mutates, re-imports (best-effort RMW)\nqa-use test vars list  --id <uuid>\nqa-use test vars set   --id <uuid> --key user --value alice\nqa-use test vars unset --id <uuid> --key user\n```\n\n**Rules:**\n\n- **Mutual exclusion**: pass either `<file>` *or* `--id`, not both. Neither \u2192 exit 1.\n- **`--id` requires a full UUID** (use `qa-use test list --query <name>` to find one).\n- **Form upgrade**: passing only `--key`/`--value` writes simple form (`key: value`).\n  Any of `--type`/`--lifetime`/`--context`/`--sensitive` upgrades to full form\n  (`{ value, type, lifetime, context, is_sensitive }`).\n- **Sensitive-preserve**: on an existing sensitive var, `--sensitive` *without*\n  `--value` keeps the stored value. On a new key, that combination errors out.\n- **`--json` redaction**: sensitive entries omit the `value` key entirely; the\n  `is_sensitive: true` flag is the redaction signal.\n- **Remote round-trip caveat**: comment/key-order preservation only applies to\n  the local-file path. The server normalizes formatting on import.\n\n**No Plugin Shortcut** - Use CLI commands directly.\n\n### 5. Test Sync Lifecycle\n\n**CLI Workflow:**\n```bash\n# Pull tests from cloud\nqa-use test sync pull\n\n# Push all local tests to cloud\nqa-use test sync push --all\n\n# Push specific test\nqa-use test sync push --id <uuid>\n\n# Force push (overwrite conflicts)\nqa-use test sync push --force\n\n# Compare local vs cloud\nqa-use test diff login.yaml\n```\n\n**Persist vs Sync:**\n\nA local test is **synced** when its YAML has both an `id:` and a `version_hash:`\n(these are written back by `test sync push`/`pull`). `--persist` on `test run`\nand `qa-use test sync` are related but not the same:\n\n| Local file state | `persist` | What happens at run time |\n|---|---|---|\n| Non-synced | `false` (default) | Runs locally; nothing saved to cloud. Re-run with `--persist` or use `test sync push` to persist. |\n| Non-synced | `true` | Test is uploaded as a **new** cloud entry after the run. Re-running like this creates **duplicates** \u2014 prefer `test sync push` once the file tracks the cloud id. |\n| Synced | `false` | Runs against the cloud-tracked definition; no extra write. |\n| Synced | `true` | Cloud definition is **upserted** (may overwrite newer cloud edits). Use `test sync push`/`pull` for explicit version control. |\n\nRule of thumb: `test sync push`/`pull` is the deliberate path. Reserve `--persist`\n(or `defaults.persist: true` in `.qa-use.json`) for one-off uploads of brand-new\nlocal tests.\n\n**No Plugin Shortcut** - Use CLI commands directly\n\n## Essential Commands\n\n### Browser Session Management\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser create` | Create remote browser session |\n| `qa-use browser create <url>` | Create session and navigate to URL |\n| `qa-use browser create --tunnel [auto\\|on\\|off]` | Tunnel mode \u2014 default `auto` (localhost + remote API). `--no-tunnel` is sugar for `off`. |\n| `qa-use browser create --no-headless` | Show browser window (paired with a local/tunnel browser) |\n| `qa-use browser create --viewport <size>` | Set viewport: `desktop`, `tablet`, `mobile` |\n| `qa-use browser create --ws-url <url>` | Connect to existing WebSocket browser |\n| `qa-use browser create --after-test-id <uuid>` | Run a test first, then become interactive |\n| `qa-use browser create --var <key=value>` | Override app config variables (repeatable) |\n| `qa-use browser list` | List active sessions |\n| `qa-use browser status` | Show current session details (app_url, recording_url, etc.) |\n| `qa-use browser status --list` | Show all active sessions across processes |\n| `qa-use browser close` | Close active session |\n| `qa-use browser close <id>` | Close a specific session by id |\n| `qa-use doctor` | Reap stale sessions/tunnels (dead PIDs) |\n| `qa-use tunnel ls` | List active tunnels in the registry |\n| `qa-use tunnel start <url> --hold` | Hold a public tunnel for external consumers |\n\nSessions auto-persist in `~/.qa-use.json`. One active session = no `-s` flag needed. `browser create` returns immediately \u2014 the browser + tunnel run in a detached child. Use `qa-use doctor` if stale state accumulates.\n\n### Navigation\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser goto <url>` | Navigate to URL |\n| `qa-use browser back` | Go back |\n| `qa-use browser forward` | Go forward |\n| `qa-use browser reload` | Reload page |\n\n### Element Interaction\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser click <ref>` | Click element by ref |\n| `qa-use browser click --text \"Button\"` | Click by semantic description |\n| `qa-use browser fill <ref> \"value\"` | Fill input field |\n| `qa-use browser type <ref> \"text\"` | Type with delays (for autocomplete) |\n| `qa-use browser press <key>` | Press key (e.g., `Enter`, `Tab`) |\n| `qa-use browser check <ref>` | Check checkbox |\n| `qa-use browser uncheck <ref>` | Uncheck checkbox |\n| `qa-use browser select <ref> \"option\"` | Select dropdown option |\n| `qa-use browser hover <ref>` | Hover over element |\n| `qa-use browser scroll down 500` | Scroll by pixels |\n| `qa-use browser scroll-into-view <ref>` | Scroll element into view |\n| `qa-use browser drag <ref> --target <ref>` | Drag element to target |\n| `qa-use browser mfa-totp [ref] <secret>` | Generate TOTP code (optionally fill) |\n| `qa-use browser upload <ref> <file>...` | Upload file(s) to input (base64-encoded, works remote & tunnel) |\n\n### Inspection & Snapshot Diff\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser snapshot` | Get full ARIA tree with element refs (use only when diff output is insufficient) |\n| `qa-use browser url` | Get current URL |\n| `qa-use browser screenshot` | Save screenshot.png |\n| `qa-use browser screenshot file.png` | Save to custom path |\n| `qa-use browser screenshot --base64` | Output base64 to stdout |\n| `qa-use browser evaluate <expression>` | Execute JavaScript in browser context |\n\nThe snapshot-diff feature automatically displays DOM changes after each browser action:\n- **Added elements**: Shown with `+` prefix and green color \u2014 these refs are immediately usable\n- **Modified elements**: Shown with `~` prefix and yellow color, including attribute changes (`+attrs: checked`)\n- **Removed elements**: Shown with `-` prefix and red color \u2014 do NOT use these refs\n\n**Downloads:** When an action triggers a file download (e.g., clicking a download link), the response includes download info: filename, size, and a presigned URL. Use `qa-use browser downloads` to list all downloads or `--save <dir>` to save them locally.\n\nUse diff output to interact with newly appeared elements directly, without running a full `snapshot` first.\n\n### Test Operations\n\n| Command | Description |\n|---------|-------------|\n| `qa-use test run <name>` | Run test by name |\n| `qa-use test run --all` | Run all tests |\n| `qa-use test run <name> --tunnel [mode]` | Override tunnel mode (`auto`, `on`, `off`). `--no-tunnel` is sugar for `off`. Bare `--tunnel` is sugar for `on`. |\n| `qa-use test run <name> --download` | Download assets to `/tmp/qa-use/downloads/` |\n| `qa-use test run <name> --var key=value` | Override variable |\n| `qa-use test validate <name>` | Validate test syntax |\n| `qa-use test list` | List available tests |\n| `qa-use test info <name>` | Show test details (steps, tags, description) |\n| `qa-use test info --id <uuid>` | Show cloud test details by ID |\n| `qa-use test runs [name]` | List test run history |\n| `qa-use test runs --id <uuid>` | Filter runs by test ID |\n| `qa-use test runs --status failed` | Filter runs by status |\n| `qa-use test init` | Initialize test directory |\n| `qa-use test sync pull` | Pull tests from cloud |\n| `qa-use test sync push --all` | Push all local tests to cloud |\n| `qa-use test sync push --id <uuid>` | Push specific test |\n| `qa-use test sync push --force` | Push tests, overwriting conflicts |\n| `qa-use test diff <file>` | Compare local vs cloud test |\n| `qa-use test schema [path]` | View test definition schema |\n\n### API Operations (Dynamic OpenAPI)\n\n`qa-use api` dynamically discovers operations from `/api/v1/openapi.json` and caches metadata locally for offline fallback.\n\n| Command | Description |\n|---------|-------------|\n| `qa-use api` | Show help and available subcommands |\n| `qa-use api ls` | List available `/api/v1/*` routes from OpenAPI |\n| `qa-use api ls --refresh` | Force refresh OpenAPI cache |\n| `qa-use api ls --offline` | Use cached OpenAPI metadata only |\n| `qa-use api info /api/v1/<route>` | Show route details: parameters, request body, responses |\n| `qa-use api info /api/v1/<route> -X POST` | Show info for specific HTTP method |\n| `qa-use api info /api/v1/<route> --json` | Route info as JSON |\n| `qa-use api examples` | Show usage examples |\n| `qa-use api openapi` | Print OpenAPI spec URL |\n| `qa-use api openapi --raw` | Dump full OpenAPI spec as JSON |\n| `qa-use api /api/v1/tests` | Call endpoint (method inferred when possible) |\n| `qa-use api -X GET /api/v1/test-runs -f limit=5` | GET with query fields |\n| `qa-use api -X POST /api/v1/tests-actions/run --input body.json` | POST with JSON body file |\n| `qa-use api -X GET /api/v1/test-runs/<id>` | Fetch detail endpoint by ID |\n\n**No Plugin Shortcut** - Use CLI commands directly.\n\n### API Checks And Check Schedules\n\nRemote API checks are managed through first-class commands. They call the\ndesplega.ai API directly; they do not run checks locally or create browser\nsessions.\n\n| Command | Description |\n|---------|-------------|\n| `qa-use check list --app-config <id>` | List remote API checks |\n| `qa-use check info <check-id>` | Inspect one check, including dependencies and captures |\n| `qa-use check create --name <name> --app-config <id> --config check.json` | Create a check |\n| `qa-use check update <check-id> --depends-on <id> --alias <name>` | Update dependency-chain metadata |\n| `qa-use check delete <check-id> --force` | Delete a check |\n| `qa-use check-schedule list --app-config <id>` | List remote check schedules |\n| `qa-use check-schedule create --name <name> --app-config <id> --cron \"*/15 * * * *\" --check <id>` | Create an ordered schedule |\n| `qa-use check-schedule run <schedule-id> --var env=staging` | Run a schedule as a remote variable-passing chain |\n\nCommon flow:\n\n```bash\nqa-use check create \\\n  --name \"Auth token\" \\\n  --app-config <app-config-id> \\\n  --config auth-check.json \\\n  --alias auth \\\n  --capture token=$.access_token\n\nqa-use check update <claim-check-id> \\\n  --depends-on <auth-check-id> \\\n  --alias claim\n\nqa-use check-schedule create \\\n  --name \"Claims chain\" \\\n  --app-config <app-config-id> \\\n  --cron \"*/15 * * * *\" \\\n  --check <auth-check-id> \\\n  --check <claim-check-id>\n\nqa-use check-schedule run <schedule-id> --var env=staging --var claim_id=123\n```\n\nThere is no standalone `qa-use check run <check-id>` command yet because the\npublic API currently documents schedule runs, not individual check-run actions.\nUse `qa-use api info /api/v1/checks -X POST` for the current check payload\ncontract, and see [references/checks.md](references/checks.md) for examples.\n\n**No Plugin Shortcut** - Use CLI commands directly.\n\n### Logs & Debugging\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser logs console` | View console logs from session |\n| `qa-use browser logs console -s <id>` | View logs from specific/closed session |\n| `qa-use browser logs network` | View network request logs |\n| `qa-use browser logs network -s <id>` | View network logs from specific session |\n| `qa-use browser downloads` | List downloaded files from session |\n| `qa-use browser downloads --save <dir>` | Save downloaded files to local directory |\n| `qa-use browser downloads --json` | Output download info as JSON |\n\n### Test Generation\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser generate-test` | Generate test YAML from recorded session |\n| `qa-use browser generate-test -s <id>` | Generate from specific session |\n| `qa-use browser generate-test -n <name>` | Specify test name |\n| `qa-use browser generate-test -o <path>` | Specify output path |\n| `qa-use browser get-blocks` | Get recorded interaction blocks (JSON) |\n\n### Waiting\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser wait <ms>` | Fixed wait |\n| `qa-use browser wait-for-selector \".class\"` | Wait for selector |\n| `qa-use browser wait-for-load` | Wait for page load |\n\n### Variable Overrides\n\nUse `--var` to override app config variables at runtime. Common variables:\n\n| Variable | Description |\n|----------|-------------|\n| `base_url` | Base URL for the app (e.g., preview deployment URL) |\n| `login_url` | Login page URL |\n| `login_username` | Username/email for authentication |\n| `login_password` | Password for authentication |\n\nExample with ephemeral preview URL:\n```bash\nqa-use browser create --after-test-id <login-test-uuid> \\\n  --var base_url=https://preview-123.example.com \\\n  --var login_url=https://preview-123.example.com/auth/login\n```\n\n## Common Patterns\n\n### Pattern 1: Feature Verification\n\n**CLI Workflow:**\n```bash\n# 1. Search for existing test\nqa-use test list | grep \"login\"\n\n# 2. Run test\nqa-use test run login\n\n# 3. Debug failures\nqa-use browser logs console\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:verify \"login works with valid credentials\"\n```\n(Wraps the above CLI workflow with AI-powered test discovery and analysis)\n\n### Pattern 2: Record & Generate Test\n\n**CLI Workflow:**\n```bash\n# 1. Create session (auto-tunnels localhost targets)\nqa-use browser create --no-headless\n\n# 2. Navigate and interact\nqa-use browser goto https://example.com\nqa-use browser snapshot\nqa-use browser click e1\nqa-use browser fill e5 \"test\"\n\n# 3. Generate test from blocks\nqa-use browser get-blocks\nqa-use browser generate-test -n \"my_test\"\n\n# 4. Run test\nqa-use test run my_test\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record start my_test\n# ... perform interactions ...\n/qa-use:record stop\n```\n\n### Pattern 3: Authenticated Exploration\n\n**CLI Workflow:**\n```bash\n# Create session that runs login test first\nqa-use browser create --after-test-id <login-test-uuid>\n\n# Session now authenticated, explore\nqa-use browser goto /dashboard\nqa-use browser snapshot\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:explore /dashboard\n```\n(Automatically handles auth detection and session creation)\n\n### Pattern 4: Edit Existing Test\n\n**CLI Workflow:**\n```bash\n# 1. Open test file in editor\nvim qa-tests/login.yaml\n\n# 2. Validate syntax\nqa-use test validate login\n\n# 3. Run to verify\nqa-use test run login\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record edit login\n```\n(AI-assisted editing with validation)\n\n### Pattern 5: Using Snapshot Diff to Avoid Unnecessary Snapshots\n\n**CLI Workflow:**\n```bash\n# Create session and navigate\nqa-use browser create --no-headless\nqa-use browser goto https://evals.desplega.ai/checkboxes\n\n# goto shows diff \u2014 initial page load shows all elements:\n# Changes: 45 elements added\n# + [e18] checkbox \"I agree to the terms and conditions\"\n# + [e19] generic \"I agree to the terms and conditions\"\n\n# \u2705 Use ref from diff directly \u2014 no snapshot needed!\nqa-use browser click e18\n\n# Diff shows what changed:\n# Changes: 5 elements added, 1 element modified\n# + [e54] generic \"Thanks for agreeing!\"\n# + [e55] link \"Terms and Conditions\"\n# ~ [e18] checkbox \"I agree to the terms and conditions\"\n#     +attrs: active, checked\n\n# \u2705 Can click e55 directly from diff output \u2014 no snapshot needed!\nqa-use browser click e55\n\n# \u274C Need to find an element NOT in the diff? Now run snapshot:\nqa-use browser snapshot\n```\n\n**Key principle:** Use diff output as your primary source of element refs after actions. Only fall back to `snapshot` when you need to find elements that weren't in the diff.\n\n**Benefits:**\n- Fewer API calls = faster automation\n- Diff refs are always fresh (just returned from the server)\n- Instantly see what changed (new elements, attribute changes, removals)\n\n**No Plugin Shortcut** - Automatic feature in all browser commands\n\n## CI/CD Integration\n\n### Running Tests in CI\n\n**Environment Variables:**\n```bash\nexport QA_USE_API_KEY=\"your-api-key\"\nexport QA_USE_REGION=\"us\"  # Optional: \"us\" or \"auto\"\n```\n\n**Basic Test Execution:**\n```bash\n# Run all tests\nqa-use test run --all\n\n# Run specific tag\nqa-use test run --tag smoke\n\n# Exit codes: 0 = pass, 1 = fail\n```\n\n### GitHub Actions Example\n\n```yaml\nname: QA Tests\non: [push, pull_request]\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-node@v3\n        with:\n          node-version: '20'\n      - name: Install qa-use\n        run: npm install -g @desplega.ai/qa-use\n      - name: Run tests\n        run: qa-use test run --all\n        env:\n          QA_USE_API_KEY: ${{ secrets.QA_USE_API_KEY }}\n```\n\n### Test Artifacts\n\n**Screenshots:**\n- Automatically saved on failure\n- Location: `/tmp/qa-use/downloads/` (local) or cloud (remote)\n\n**Logs:**\n- Console logs: `qa-use browser logs console -s <session-id>`\n- Network logs: `qa-use browser logs network -s <session-id>`\n\n## Advanced Topics\n\n### Localhost Testing (Auto-Tunnel)\n\n**qa-use auto-tunnels localhost targets when the API is remote.** No flag required for the common case:\n\n```bash\nqa-use browser create --no-headless http://localhost:3000\nqa-use test run my_test   # auto-tunnels if base_url is localhost\n```\n\n**Tri-state `--tunnel` flag:**\n\n| Value | Behavior |\n|-------|----------|\n| `auto` (default) | Tunnel iff base URL is localhost AND API URL is remote |\n| `on` (or bare `--tunnel`) | Force a tunnel even in dev mode |\n| `off` (or `--no-tunnel`) | Never tunnel |\n\n```\nTesting localhost (http://localhost:3000)?\n  \u251C\u2500 API remote (default)  \u2192 auto-tunnels. No flag needed.\n  \u251C\u2500 API also local (dev)  \u2192 no tunnel by default. Use --tunnel on to force.\n  \u2514\u2500 Public URL target     \u2192 no tunnel (remote cloud browser)\n```\n\n**Plugin shortcuts handle tunnel detection automatically:**\n```\n/qa-use:explore http://localhost:3000\n/qa-use:record start local_test\n```\n\nSee [references/localhost-testing.md](references/localhost-testing.md) for troubleshooting.\n\n### Session Persistence\n\nSessions are stored in `~/.qa-use.json` and have:\n- **TTL**: 30 minutes (default)\n- **Auto-resolve**: One active session = no `-s` flag needed\n- **Cleanup**: Automatic on timeout or explicit `browser close`\n\n### Block Limitations\n\n**What's captured:**\n- goto, click, fill, type, check, uncheck, select, hover\n- scroll, scroll-into-view, drag, upload, press\n\n**What's NOT captured:**\n- Assertions (must be added manually)\n- Waits (inferred from timing, may need adjustment)\n- Complex interactions (multi-drag, hover sequences)\n\n**Manual editing:** Edit generated YAML to add assertions and refine selectors.\n\n### WebSocket Sessions\n\n**Sharing sessions across processes:**\n```bash\n# Process 1: Create session (auto-tunnels if target is localhost + API remote)\nqa-use browser create http://localhost:3000\n# Output: ws://localhost:12345/browser/abc123\n\n# Process 2: Connect to session\nqa-use browser goto https://example.com --ws-url ws://localhost:12345/browser/abc123\n```\n\n## Deep-Dive References\n\nAccess any reference at runtime via the CLI: `qa-use docs <topic>`\n\n| Topic | CLI Command | Description |\n|-------|-------------|-------------|\n| [browser-commands.md](references/browser-commands.md) | `qa-use docs browser-commands` | Complete browser CLI reference with all flags |\n| [checks.md](references/checks.md) | `qa-use docs checks` | API checks and check schedule workflows |\n| [test-format.md](references/test-format.md) | `qa-use docs test-format` | Full test YAML specification |\n| [localhost-testing.md](references/localhost-testing.md) | `qa-use docs localhost-testing` | Tunnel setup for local development |\n| [failure-debugging.md](references/failure-debugging.md) | `qa-use docs failure-debugging` | Failure classification and diagnostics |\n| [ci.md](references/ci.md) | `qa-use docs ci` | CI/CD integration patterns and examples |\n\nUse `qa-use docs --list` to discover all available topics and templates.\n\n## Templates\n\n| Template | Description |\n|----------|-------------|\n| [basic-test.yaml](templates/basic-test.yaml) | Simple navigation and assertion |\n| [auth-flow.yaml](templates/auth-flow.yaml) | Login flow with credentials |\n| [form-test.yaml](templates/form-test.yaml) | Form submission with validation |\n\n## Test Format Overview\n\n```yaml\nname: Login Test\ndescription: Validates login functionality with valid credentials\ntags:\n  - smoke\n  - auth\napp_config: <app-config-id>\nvariables:\n  email: test@example.com\n  password: secret123\ndepends_on: setup-test  # Optional\nsteps:\n  - action: goto\n    url: /login\n  - action: fill\n    target: email input\n    value: $email\n  - action: click\n    target: login button\n  - action: to_be_visible\n    target: dashboard\n```\n\nSee [references/test-format.md](references/test-format.md) for complete specification.\n\n## Common Mistakes\n\n| \u274C Wrong | \u2705 Correct |\n|---------|-----------|\n| `browser navigate <url>` | `browser goto <url>` |\n| `browser destroy` | `browser close` |\n| `browser close <session-id>` | `browser close` |\n| Guessing element refs | Use refs from diff output or `snapshot` |\n| Running `snapshot` after every action | Use diff output; only `snapshot` when needed |\n| Forcing `--tunnel` in dev (both local) | Rely on auto-mode, or use `--tunnel on` explicitly |\n| `test sync --pull` | `test sync pull` (subcommand, not flag) |\n| `test sync --push` | `test sync push` (subcommand, not flag) |\n\n## Troubleshooting\n\nWhen stuck or encountering unexpected errors, use the built-in documentation:\n\n```bash\n# Check configuration state\nqa-use setup\n\n# Browse main documentation\nqa-use docs\n\n# List all available topics\nqa-use docs --list\n\n# Access specific topic\nqa-use docs <topic>\n```\n\n| Situation | Command |\n|-----------|---------|\n| Auth / API key errors | `qa-use setup` then `qa-use docs` |\n| Unknown browser command | `qa-use docs browser-commands` |\n| Test failures | `qa-use docs failure-debugging` |\n| Localhost / tunnel issues | `qa-use docs localhost-testing` |\n| Test YAML syntax | `qa-use docs test-format` |\n| API checks / schedules | `qa-use docs checks` |\n| CI/CD setup | `qa-use docs ci` |\n\n**Key rules:**\n- ALWAYS consult `qa-use docs` before improvising workarounds\n- NEVER fabricate API keys, tokens, URLs, or credentials\n- If `qa-use setup` shows no config, report it \u2014 don't guess\n\n## npx Alternative\n\nAll commands use `qa-use` assuming global install. For one-off use:\n```bash\nnpx @desplega.ai/qa-use browser <command>\n```\n";
 export declare const REFERENCE_DOCS: Record<string, {
     title: string;
     content: string;

package/dist/src/cli/generated/docs-content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-content.d.ts","sourceRoot":"","sources":["../../../../src/cli/generated/docs-content.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,QAAQ,484BAuxBpB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA2qD7E,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiIxE,CAAC"}
+{"version":3,"file":"docs-content.d.ts","sourceRoot":"","sources":["../../../../src/cli/generated/docs-content.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,QAAQ,wg9BAy0BpB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAi2D7E,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiIxE,CAAC"}

package/dist/src/cli/generated/docs-content.js

@@ -400,6 +400,54 @@ Use diff output to interact with newly appeared elements directly, without runni
 
 **No Plugin Shortcut** - Use CLI commands directly.
 
+### API Checks And Check Schedules
+
+Remote API checks are managed through first-class commands. They call the
+desplega.ai API directly; they do not run checks locally or create browser
+sessions.
+
+| Command | Description |
+|---------|-------------|
+| \`qa-use check list --app-config <id>\` | List remote API checks |
+| \`qa-use check info <check-id>\` | Inspect one check, including dependencies and captures |
+| \`qa-use check create --name <name> --app-config <id> --config check.json\` | Create a check |
+| \`qa-use check update <check-id> --depends-on <id> --alias <name>\` | Update dependency-chain metadata |
+| \`qa-use check delete <check-id> --force\` | Delete a check |
+| \`qa-use check-schedule list --app-config <id>\` | List remote check schedules |
+| \`qa-use check-schedule create --name <name> --app-config <id> --cron "*/15 * * * *" --check <id>\` | Create an ordered schedule |
+| \`qa-use check-schedule run <schedule-id> --var env=staging\` | Run a schedule as a remote variable-passing chain |
+
+Common flow:
+
+\`\`\`bash
+qa-use check create \\
+  --name "Auth token" \\
+  --app-config <app-config-id> \\
+  --config auth-check.json \\
+  --alias auth \\
+  --capture token=$.access_token
+
+qa-use check update <claim-check-id> \\
+  --depends-on <auth-check-id> \\
+  --alias claim
+
+qa-use check-schedule create \\
+  --name "Claims chain" \\
+  --app-config <app-config-id> \\
+  --cron "*/15 * * * *" \\
+  --check <auth-check-id> \\
+  --check <claim-check-id>
+
+qa-use check-schedule run <schedule-id> --var env=staging --var claim_id=123
+\`\`\`
+
+There is no standalone \`qa-use check run <check-id>\` command yet because the
+public API currently documents schedule runs, not individual check-run actions.
+Use \`qa-use api info /api/v1/checks -X POST\` for the current check payload
+contract, and see [references/checks.md](references/checks.md) for examples.
+
+**No Plugin Shortcut** - Use CLI commands directly.
+
 ### Logs & Debugging
 
 | Command | Description |
@@ -701,6 +749,7 @@ Access any reference at runtime via the CLI: \`qa-use docs <topic>\`
 | Topic | CLI Command | Description |
 |-------|-------------|-------------|
 | [browser-commands.md](references/browser-commands.md) | \`qa-use docs browser-commands\` | Complete browser CLI reference with all flags |
+| [checks.md](references/checks.md) | \`qa-use docs checks\` | API checks and check schedule workflows |
 | [test-format.md](references/test-format.md) | \`qa-use docs test-format\` | Full test YAML specification |
 | [localhost-testing.md](references/localhost-testing.md) | \`qa-use docs localhost-testing\` | Tunnel setup for local development |
 | [failure-debugging.md](references/failure-debugging.md) | \`qa-use docs failure-debugging\` | Failure classification and diagnostics |
@@ -781,6 +830,7 @@ qa-use docs <topic>
 | Test failures | \`qa-use docs failure-debugging\` |
 | Localhost / tunnel issues | \`qa-use docs localhost-testing\` |
 | Test YAML syntax | \`qa-use docs test-format\` |
+| API checks / schedules | \`qa-use docs checks\` |
 | CI/CD setup | \`qa-use docs ci\` |
 
 **Key rules:**
@@ -1306,6 +1356,160 @@ See [localhost-testing.md](localhost-testing.md) for full tunnel mode documentat
 ---
 
 > **Runtime access:** \`qa-use docs browser-commands\` | All topics: \`qa-use docs --list\`
+`,
+    },
+    checks: {
+        title: 'API Checks And Check Schedules',
+        content: `# API Checks And Check Schedules
+
+\`qa-use check\` and \`qa-use check-schedule\` manage remote desplega.ai API
+checks. These commands call \`/api/v1/*\` endpoints directly. They do not start a
+browser session and they do not run checks locally.
+
+Use the live API contract when you need exact payload fields:
+
+\`\`\`bash
+qa-use api info /api/v1/checks -X POST
+qa-use api info /api/v1/check-schedules -X POST
+qa-use api info /api/v1/check-schedules-actions/run -X POST
+\`\`\`
+
+## Inspect Checks
+
+\`\`\`bash
+qa-use check list --app-config <app-config-id> --q login
+qa-use check list --json --limit 10
+qa-use check info <check-id>
+qa-use check info <check-id> --json
+\`\`\`
+
+Human \`info\` output highlights dependency-chain fields such as \`alias\`,
+\`check_dependency_ids\`, \`output_captures\`, variables, retry settings, and
+timeouts. Use \`--json\` when you need the raw API shape.
+
+## Create Checks
+
+The \`config\` and \`validation\` objects are backend-defined. Keep the JSON in a
+file for repeatable CLI usage, and confirm the current schema with
+\`qa-use api info /api/v1/checks -X POST\`.
+
+Example \`auth-check.json\`:
+
+\`\`\`json
+{
+  "method": "POST",
+  "url": "{{base_url}}/api/login",
+  "headers": {
+    "content-type": "application/json"
+  },
+  "body": {
+    "email": "{{email}}",
+    "password": "{{password}}"
+  }
+}
+\`\`\`
+
+Create the check and expose captured outputs to downstream checks:
+
+\`\`\`bash
+qa-use check create \\
+  --name "Auth token" \\
+  --app-config <app-config-id> \\
+  --config auth-check.json \\
+  --alias auth \\
+  --capture token=$.access_token \\
+  --capture user_id=$.user.id \\
+  --var env=staging \\
+  --timeout-ms 15000
+\`\`\`
+
+For full control, pass raw API fields through \`--input\` or repeatable \`-F\`:
+
+\`\`\`bash
+qa-use check create --input check-create-body.json
+printf '{"name":"Login","app_config_id":"<id>","config":{}}' |
+  qa-use check create --input -
+qa-use check create \\
+  -F name="Auth token" \\
+  -F app_config_id=<app-config-id> \\
+  -F config='{"method":"GET","url":"{{base_url}}/health"}'
+\`\`\`
+
+## Dependencies And Captures
+
+Use \`--depends-on\` to declare upstream checks. Use \`--alias\` to name the check
+inside the chain, and \`--capture name=json_path\` to publish response values to
+later checks.
+
+\`\`\`bash
+qa-use check update <claim-check-id> \\
+  --depends-on <auth-check-id> \\
+  --alias claim \\
+  --capture claim_id=$.claim.id
+\`\`\`
+
+You can repeat \`--depends-on\` and \`--capture\`:
+
+\`\`\`bash
+qa-use check update <report-check-id> \\
+  --depends-on <auth-check-id> \\
+  --depends-on <claim-check-id> \\
+  --capture report_id=$.id \\
+  --capture status=$.status
+\`\`\`
+
+## Create And Run Schedules
+
+Schedules run checks remotely in dependency-graph order. The order of
+repeatable \`--check\` flags is preserved in the request body as \`check_ids\`.
+
+\`\`\`bash
+qa-use check-schedule create \\
+  --name "Claims chain" \\
+  --app-config <app-config-id> \\
+  --cron "*/15 * * * *" \\
+  --timezone UTC \\
+  --check <auth-check-id> \\
+  --check <claim-check-id> \\
+  --failure-strategy stop_on_failure
+\`\`\`
+
+Run the remote schedule chain with seed variables:
+
+\`\`\`bash
+qa-use check-schedule run <schedule-id> \\
+  --var env=staging \\
+  --var claim_id=123
+\`\`\`
+
+The schedule-run response is currently untyped in the public OpenAPI contract.
+Human output prints any recognized run id or status fields, and \`--json\` prints
+the raw response.
+
+## Delete Resources
+
+Deletion is remote and permanent. Use \`--force\` for non-interactive cleanup:
+
+\`\`\`bash
+qa-use check-schedule delete <schedule-id> --force
+qa-use check delete <check-id> --force
+\`\`\`
+
+When scripting cleanup, delete schedules before deleting checks that they
+reference.
+
+## Current Run Limitation
+
+The public API currently documents \`POST /api/v1/check-schedules-actions/run\`.
+It does not document a standalone \`POST /api/v1/checks-actions/run\` endpoint or
+check-run history endpoints. For that reason, qa-use exposes
+\`qa-use check-schedule run <schedule-id>\` but does not expose
+\`qa-use check run <check-id>\`.
+
+Do not create temporary schedules to fake a standalone check run in user
+workflows unless product explicitly asks for that behavior.
+
+> Runtime access: \`qa-use docs checks\` | All topics: \`qa-use docs --list\`
 `,
     },
     ci: {
@@ -2396,6 +2600,34 @@ The \`target_locator\` must be a valid Playwright locator string:
         args: ["Enter your code"]
 \`\`\`
 
+### API Check Steps
+
+Embedded API checks use the extended step format. The live test-definition
+schema exposes the \`api_check\` action, a \`value.check_id\` field, and
+\`context: check\` for typed variables:
+
+\`\`\`yaml
+name: api-check-step-example
+variables:
+  env:
+    value: staging
+    type: custom
+    lifetime: test
+    context: check
+steps:
+  - type: extended
+    name: Run authentication API check
+    action:
+      action: api_check
+      value:
+        check_id: 00000000-0000-0000-0000-000000000000
+\`\`\`
+
+Use check-scoped variables for values the embedded API check needs from the
+parent test. API-check output variables are not declared in this YAML schema;
+configure output captures on the remote check, then reference backend-exposed
+variables in later steps using the existing variable syntax.
+
 **Tip:** Use \`qa-use test schema\` to explore all available actions and their schemas.
 
 ## Target Descriptions

package/dist/src/cli/generated/docs-content.js.map

@@ -1 +1 @@
-{"version":3,"file":"docs-content.js","sourceRoot":"","sources":["../../../../src/cli/generated/docs-content.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"docs-content.js","sourceRoot":"","sources":["../../../../src/cli/generated/docs-content.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAy0BvB,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAuD;IAChF,kBAAkB,EAAE;QAClB,KAAK,EAAE,4BAA4B;QACnC,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4fZ;KACE;IACD,MAAM,EAAE;QACN,KAAK,EAAE,gCAAgC;QACvC,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsJZ;KACE;IACD,EAAE,EAAE;QACF,KAAK,EAAE,sBAAsB;QAC7B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwVZ;KACE;IACD,mBAAmB,EAAE;QACnB,KAAK,EAAE,mBAAmB;QAC1B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsNZ;KACE;IACD,mBAAmB,EAAE;QACnB,KAAK,EAAE,mBAAmB;QAC1B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkNZ;KACE;IACD,aAAa,EAAE;QACb,KAAK,EAAE,uBAAuB;QAC9B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsbZ;KACE;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAuD;IAC3E,WAAW,EAAE;QACX,KAAK,EAAE,oBAAoB;QAC3B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CZ;KACE;IACD,YAAY,EAAE;QACZ,KAAK,EAAE,qBAAqB;QAC5B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;CAuBZ;KACE;IACD,WAAW,EAAE;QACX,KAAK,EAAE,oBAAoB;QAC3B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiDZ;KACE;CACF,CAAC"}

package/dist/src/cli/index.js

@@ -8,6 +8,8 @@ import { apiCommand } from './commands/api/index.js';
 import { appConfigCommand } from './commands/app-config/index.js';
 import { appContextCommand } from './commands/app-context/index.js';
 import { browserCommand } from './commands/browser/index.js';
+import { checkCommand } from './commands/check/index.js';
+import { checkScheduleCommand } from './commands/check-schedule/index.js';
 import { dataAssetCommand } from './commands/data-asset/index.js';
 import { docsCommand } from './commands/docs.js';
 import { doctorCommand } from './commands/doctor.js';
@@ -40,6 +42,8 @@ program.addCommand(testCommand);
 program.addCommand(suiteCommand);
 program.addCommand(mcpCommand);
 program.addCommand(browserCommand);
+program.addCommand(checkCommand);
+program.addCommand(checkScheduleCommand);
 program.addCommand(tunnelCommand());
 program.addCommand(installDepsCommand);
 program.addCommand(updateCommand);
@@ -78,6 +82,7 @@ Command Groups:
   Runs:      test runs list, test runs info, test runs steps
   Suites:    suite list, suite create, suite run
   Issues:    issues list, issues info, issues occurrences
+  Checks:    check list, check info, check-schedule run
   Browser:   browser create, browser goto, browser snapshot, browser click
   Config:    app-config list, app-config create
   Context:   app-context list, app-context create
@@ -115,6 +120,12 @@ Common Workflows:
   qa-use suite list
   qa-use suite run <suite-id>
 
+  # Inspect remote API checks
+  qa-use check list --limit 5
+  qa-use check info <check-id>
+  qa-use check-schedule list --limit 5
+  qa-use check-schedule run <schedule-id> --var env=staging
+
   # Review test run results
   qa-use test runs list --limit 5
   qa-use test runs info <run-id>

package/dist/src/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AAEA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAE/B,gCAAgC;AAChC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAElD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,QAAQ,CAAC;KACd,WAAW,CAAC,uDAAuD,CAAC;KACpE,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,oBAAoB;AACpB,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,oBAAoB,CAAC,CAAC;AACzC,OAAO,CAAC,UAAU,CAAC,aAAa,EAAE,CAAC,CAAC;AACpC,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AACvC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;AACrC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;AACtC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;AACrC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAElC,2EAA2E;AAC3E,0EAA0E;AAC1E,mBAAmB,EAAE,CAAC;AAEtB,wEAAwE;AACxE,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;IACnC,yBAAyB,CAAC,OAAO,CAAC,CAAC;IACnC,mBAAmB,EAAE,CAAC;AACxB,CAAC;AAED,iDAAiD;AACjD,OAAO,CAAC,WAAW,CACjB,QAAQ,EACR;;;;;;;CAOD,CACA,CAAC;AAEF,iEAAiE;AACjE,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE;IAChC,MAAM,UAAU,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8DP,UAAU,EAAE,CAAC;AACf,CAAC,CAAC,CAAC;AAEH,+BAA+B;AAC/B,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/src/cli/lib/api-helpers.d.ts

@@ -40,16 +40,17 @@ export declare function paginationQuery(options: {
  */
 export declare function collectFields(value: string, previous: string[]): string[];
 /**
- * Reads body from `--input` file and/or `-F` fields and merges them.
+ * Reads body from `--input` file/stdin and/or `-F` fields and merges them.
  * Values that parse as valid JSON are treated as JSON
  * (e.g. `-F test_ids='["id1","id2"]'`).
  *
- * Stdin (piped) is intentionally **not** read here — that would complicate
- * interactive commands. Add it later if needed.
+ * Stdin is read only when `--input -` is provided explicitly. There is no
+ * implicit stdin sniffing, so interactive commands do not hang unexpectedly.
  */
 export declare function parseResourceInput(options: {
     input?: string;
     field?: string[];
+    stdin?: NodeJS.ReadableStream;
 }): Promise<Record<string, unknown>>;
 /**
  * Confirmation prompt for destructive operations.

package/dist/src/cli/lib/api-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-helpers.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/api-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,MAAM,IAAI,SAAS,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAMnD;AAMD,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,OAAO,CAAC,CAoBlB;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKzB;AAMD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAGzE;AAMD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA4CnC;AAMD;;;GAGG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYrE"}
+{"version":3,"file":"api-helpers.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/api-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,MAAM,IAAI,SAAS,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAMnD;AAMD,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,OAAO,CAAC,CAoBlB;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKzB;AAMD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAGzE;AAMD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;CAC/B,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAiDnC;AAMD;;;GAGG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYrE"}

package/dist/src/cli/lib/api-helpers.js

@@ -6,6 +6,7 @@
  */
 import * as fs from 'node:fs/promises';
 import * as readline from 'node:readline/promises';
+import { text as readStreamText } from 'node:stream/consumers';
 import { executeApiRequest, formatApiResponseError } from '../commands/api/lib/http.js';
 // ---------------------------------------------------------------------------
 // requireApiKey
@@ -76,30 +77,35 @@ export function collectFields(value, previous) {
 // parseResourceInput
 // ---------------------------------------------------------------------------
 /**
- * Reads body from `--input` file and/or `-F` fields and merges them.
+ * Reads body from `--input` file/stdin and/or `-F` fields and merges them.
  * Values that parse as valid JSON are treated as JSON
  * (e.g. `-F test_ids='["id1","id2"]'`).
  *
- * Stdin (piped) is intentionally **not** read here — that would complicate
- * interactive commands. Add it later if needed.
+ * Stdin is read only when `--input -` is provided explicitly. There is no
+ * implicit stdin sniffing, so interactive commands do not hang unexpectedly.
  */
 export async function parseResourceInput(options) {
     let base = {};
-    // 1. --input file
+    // 1. --input file or explicit stdin
     if (options.input) {
-        const raw = await fs.readFile(options.input, 'utf-8');
+        const fromStdin = options.input === '-';
+        const raw = fromStdin
+            ? await readStreamText(options.stdin ?? process.stdin)
+            : await fs.readFile(options.input, 'utf-8');
         try {
             const parsed = JSON.parse(raw);
             if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
                 base = parsed;
             }
             else {
-                throw new Error(`Input file must contain a JSON object, got ${typeof parsed}`);
+                const source = fromStdin ? 'Input from stdin' : 'Input file';
+                throw new Error(`${source} must contain a JSON object, got ${typeof parsed}`);
             }
         }
         catch (err) {
             if (err instanceof SyntaxError) {
-                throw new Error(`Failed to parse JSON input file: ${options.input}`);
+                const source = fromStdin ? 'stdin' : `file: ${options.input}`;
+                throw new Error(`Failed to parse JSON input from ${source}`);
             }
             throw err;
         }

package/dist/src/cli/lib/api-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-helpers.js","sourceRoot":"","sources":["../../../../src/cli/lib/api-helpers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-helpers.js","sourceRoot":"","sources":["../../../../src/cli/lib/api-helpers.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/lib/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/browser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,KAAK,YAAY,EAAkB,MAAM,iCAAiC,CAAC;AAIpF,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAiBzE,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,cAAc,CAAC;IACxB;;;;OAIG;IACH,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B,gEAAgE;IAChE,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAY9C;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAmF/B;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAEvE;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAaxF"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/browser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAG/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,KAAK,YAAY,EAAkB,MAAM,iCAAiC,CAAC;AAIpF,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAiBzE,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,cAAc,CAAC;IACxB;;;;OAIG;IACH,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B,gEAAgE;IAChE,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAY9C;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAwF/B;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAEvE;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAaxF"}

package/dist/src/cli/lib/browser.js

@@ -5,6 +5,7 @@
  * and browser WebSocket connection for remote test execution.
  */
 import { BrowserManager } from '../../../lib/browser/index.js';
+import { resolveForcedHeadless } from '../../../lib/env/force-headless.js';
 import { classifyTunnelFailure, TunnelError } from '../../../lib/tunnel/errors.js';
 import { tunnelRegistry } from '../../../lib/tunnel/registry.js';
 import { error } from './output.js';
@@ -56,10 +57,12 @@ export async function startBrowserWithTunnel(testUrl, options = {}) {
     let tunnel = null;
     let tunnelHandle = null;
     let publicWsUrl = null;
-    // Start browser
+    // Start browser. resolveForcedHeadless throws on explicit headful when
+    // QA_USE_FORCE_HEADLESS is set; otherwise passthrough.
+    const headless = resolveForcedHeadless(options.headless, 'startBrowserWithTunnel({ headless: false })');
     console.error('Starting browser...');
     const browserSession = await browser.startBrowser({
-        headless: options.headless ?? true,
+        headless: headless ?? true,
     });
     const wsUrl = browserSession.wsEndpoint;
     // Resolve the on/off decision. Default mode is 'auto' — that way