@loadmill/droid-cua 2.23.0 → 2.24.0

package/README.md

@@ -134,6 +134,27 @@ Install:
 npm install -g @loadmill/droid-cua
 ```
 
+Install the bundled Agent Skill for your coding agent:
+
+```sh
+# Global installation (default)
+droid-cua skill install cursor
+droid-cua skill install claude-code
+droid-cua skill install codex
+
+# Or install in the current project
+droid-cua skill install codex --local
+```
+
+Use `droid-cua skill status <agent>` to inspect an installation and
+`droid-cua skill uninstall <agent>` to remove it. Installed skill
+files are never overwritten or removed after local modification unless `--force`
+is supplied. After upgrading the npm package, update an installed skill explicitly:
+
+```sh
+droid-cua skill install <agent> --force
+```
+
 Examples:
 ```sh
 # Interactive CLI
@@ -230,6 +251,10 @@ Supported CLI options include:
 - `--report`
 - `--debug`
 
+`--cua-model` accepts `loadmill-smart`, `loadmill-beacon`, `gpt-5.6-terra`,
+`gpt-5.6-luna`, and `gpt-5.4`. OpenAI models use direct OpenAI mode and require
+`OPENAI_API_KEY`.
+
 Config and precedence rules:
 - Use `--config <file>` to supply prompt-affecting settings for headless runs.
 - CLI flags override config file values.

package/build/index.js

@@ -29,8 +29,20 @@ import { createStatusLine } from "./src/cli/cloud-status-line.js";
 import { createLoadmillApiClient } from "./src/integrations/loadmill/client.js";
 import { getCloudProviderAdapter } from "./src/device/cloud/registry.js";
 import { setCloudProgressListener } from "./src/device/cloud/progress.js";
+import { runSkillCommand } from "./src/cli/skill-command.js";
 dotenv.config();
 const args = minimist(process.argv.slice(2));
+if (args._[0] === "skill") {
+    try {
+        await runSkillCommand({ args });
+        process.exit(0);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`\nSkill command failed: ${message}`);
+        process.exit(1);
+    }
+}
 const targetConfig = resolveHeadlessTarget(args);
 let avdName = targetConfig.avdName;
 let platform = targetConfig.platform || null; // 'ios' or 'android'

package/build/src/cli/skill-command.js

@@ -0,0 +1,240 @@
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { cp, lstat, mkdir, readdir, readFile, rm } from "node:fs/promises";
+const SKILL_NAME = "droid-cua";
+const AGENTS = Object.freeze({
+    cursor: { displayName: "Cursor", relativePath: path.join(".cursor", "skills", SKILL_NAME) },
+    "claude-code": { displayName: "Claude Code", relativePath: path.join(".claude", "skills", SKILL_NAME) },
+    codex: { displayName: "Codex", relativePath: path.join(".agents", "skills", SKILL_NAME) },
+});
+const SUBCOMMANDS = new Set(["install", "status", "uninstall"]);
+const ALLOWED_OPTIONS = new Set(["_", "local", "force", "h", "help"]);
+const COMMAND_DESCRIPTIONS = Object.freeze({
+    install: "Install Droid CUA skill for a coding agent",
+    status: "Show Droid CUA skill status for a coding agent",
+    uninstall: "Uninstall Droid CUA skill for a coding agent",
+});
+function skillCommandHelp(subcommand) {
+    const localDescriptions = {
+        install: "Install in current project instead of global",
+        status: "Check current project instead of global",
+        uninstall: "Uninstall from current project instead of global",
+    };
+    const options = [
+        `  --local      ${localDescriptions[subcommand]}`,
+    ];
+    if (subcommand !== "status") {
+        options.push("  --force      Overwrite or remove modified skill files");
+    }
+    options.push("  -h, --help  display help for command");
+    return [
+        `Usage: droid-cua skill ${subcommand} [options] [agent]`,
+        "",
+        COMMAND_DESCRIPTIONS[subcommand],
+        "",
+        "Agents:",
+        "  cursor",
+        "  claude-code",
+        "  codex",
+        "",
+        "Example:",
+        `  droid-cua skill ${subcommand} claude-code`,
+        "",
+        "Options:",
+        ...options,
+    ].join("\n");
+}
+function skillRootHelp() {
+    return [
+        "Usage: droid-cua skill <command> [options] [agent]",
+        "",
+        "Manage the bundled Droid CUA skill",
+        "",
+        "Commands:",
+        "  install    Install the skill",
+        "  status     Show installation status",
+        "  uninstall  Uninstall the skill",
+    ].join("\n");
+}
+async function pathType(targetPath) {
+    try {
+        const stats = await lstat(targetPath);
+        if (stats.isDirectory())
+            return "directory";
+        if (stats.isFile())
+            return "file";
+        if (stats.isSymbolicLink())
+            return "symlink";
+        return "other";
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return "missing";
+        throw error;
+    }
+}
+async function snapshotDirectory(rootPath, relativePath = "") {
+    const absolutePath = relativePath ? path.join(rootPath, relativePath) : rootPath;
+    const entries = await readdir(absolutePath, { withFileTypes: true });
+    const snapshot = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const childRelativePath = relativePath ? path.join(relativePath, entry.name) : entry.name;
+        if (entry.isDirectory()) {
+            snapshot.push({ path: `${childRelativePath}/`, type: "directory" });
+            snapshot.push(...await snapshotDirectory(rootPath, childRelativePath));
+        }
+        else if (entry.isFile()) {
+            const contents = await readFile(path.join(rootPath, childRelativePath));
+            snapshot.push({ path: childRelativePath, type: "file", contents: contents.toString("base64") });
+        }
+        else {
+            snapshot.push({ path: childRelativePath, type: entry.isSymbolicLink() ? "symlink" : "other" });
+        }
+    }
+    return snapshot;
+}
+async function directoryMatches(sourcePath, destinationPath) {
+    if (await pathType(destinationPath) !== "directory")
+        return false;
+    const [sourceSnapshot, destinationSnapshot] = await Promise.all([
+        snapshotDirectory(sourcePath),
+        snapshotDirectory(destinationPath),
+    ]);
+    return JSON.stringify(sourceSnapshot) === JSON.stringify(destinationSnapshot);
+}
+async function getInstallationState(sourcePath, destinationPath) {
+    if (await pathType(destinationPath) === "missing")
+        return "not-installed";
+    return await directoryMatches(sourcePath, destinationPath) ? "installed" : "modified";
+}
+function normalizeStringOption(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${label} requires a value.`);
+    }
+    return value.trim().toLowerCase();
+}
+function parseSkillCommandArgs(args) {
+    const unknownOption = Object.keys(args).find((key) => !ALLOWED_OPTIONS.has(key));
+    if (unknownOption)
+        throw new Error(`Unknown skill option --${unknownOption}.`);
+    if (!Array.isArray(args._) || args._[0] !== "skill") {
+        throw new Error("Usage: droid-cua skill <command> [options] [agent]");
+    }
+    if (args._.length === 1) {
+        return { help: skillRootHelp() };
+    }
+    const subcommand = normalizeStringOption(args._[1], "Skill subcommand");
+    if (!SUBCOMMANDS.has(subcommand)) {
+        throw new Error(`Unknown skill subcommand "${subcommand}". Expected install, status, or uninstall.`);
+    }
+    for (const option of ["local", "force", "h", "help"]) {
+        if (args[option] != null && typeof args[option] !== "boolean") {
+            throw new Error(`--${option === "h" ? "help" : option} does not accept a value.`);
+        }
+    }
+    if (args.help === true || args.h === true || args._.length === 2) {
+        return { help: skillCommandHelp(subcommand) };
+    }
+    if (args._.length !== 3)
+        throw new Error(skillCommandHelp(subcommand));
+    if (subcommand === "status" && args.force != null) {
+        throw new Error("--force is only supported by install and uninstall.");
+    }
+    const agent = normalizeStringOption(args._[2], "Agent");
+    if (!Object.hasOwn(AGENTS, agent)) {
+        throw new Error(`Unknown agent "${agent}". Expected cursor, claude-code, or codex.`);
+    }
+    return {
+        subcommand,
+        agent,
+        local: args.local === true,
+        force: args.force === true,
+    };
+}
+export function resolveSkillDestination({ agent, local = false, cwd = process.cwd(), home = os.homedir() }) {
+    const basePath = local ? cwd : home;
+    return {
+        agent,
+        ...AGENTS[agent],
+        path: path.join(basePath, AGENTS[agent].relativePath),
+    };
+}
+export async function resolveBundledSkillPath({ startDir = path.dirname(fileURLToPath(import.meta.url)) } = {}) {
+    let currentPath = path.resolve(startDir);
+    while (true) {
+        const candidate = path.join(currentPath, "skill", SKILL_NAME);
+        if (await pathType(path.join(candidate, "SKILL.md")) === "file")
+            return candidate;
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath)
+            break;
+        currentPath = parentPath;
+    }
+    throw new Error("Bundled Droid CUA skill was not found. Reinstall @loadmill/droid-cua and try again.");
+}
+function stateLabel(state) {
+    if (state === "not-installed")
+        return "not installed";
+    return state;
+}
+function shouldUseColor() {
+    return Boolean(process.stdout.isTTY) && !Object.hasOwn(process.env, "NO_COLOR");
+}
+function formatInstallSuccess(destination, { alreadyInstalled, color }) {
+    const checkmark = color ? "\u001b[32m✓\u001b[39m" : "✓";
+    const skillFilePath = path.join(destination.path, "SKILL.md");
+    const displayedPath = color ? `\u001b[2m${skillFilePath}\u001b[22m` : skillFilePath;
+    const message = alreadyInstalled
+        ? `${destination.agent} skill already installed`
+        : `Installed ${destination.agent} skill`;
+    return `${checkmark} ${message}\n${displayedPath}`;
+}
+export async function runSkillCommand({ args, cwd = process.cwd(), home = os.homedir(), sourcePath = null, output = console, color = shouldUseColor(), } = {}) {
+    const command = parseSkillCommandArgs(args ?? {});
+    if (command.help) {
+        output.log(command.help);
+        return [];
+    }
+    const bundledSkillPath = sourcePath ?? await resolveBundledSkillPath();
+    if (await pathType(path.join(bundledSkillPath, "SKILL.md")) !== "file") {
+        throw new Error(`Invalid bundled skill at ${bundledSkillPath}: SKILL.md is missing.`);
+    }
+    const destination = resolveSkillDestination({ agent: command.agent, local: command.local, cwd, home });
+    const states = [{
+            ...destination,
+            state: await getInstallationState(bundledSkillPath, destination.path),
+        }];
+    if (command.subcommand !== "status" && !command.force) {
+        const conflicts = states.filter(({ state }) => state === "modified");
+        if (conflicts.length > 0) {
+            const paths = conflicts.map(({ path: destinationPath }) => destinationPath).join(", ");
+            throw new Error(`Refusing to ${command.subcommand} modified skill files at ${paths}. Re-run with --force to replace them.`);
+        }
+    }
+    for (const destination of states) {
+        if (command.subcommand === "status") {
+            output.log(`${destination.displayName}: ${stateLabel(destination.state)} at ${destination.path}`);
+        }
+        else if (command.subcommand === "install") {
+            if (destination.state === "installed") {
+                output.log(formatInstallSuccess(destination, { alreadyInstalled: true, color }));
+            }
+            else {
+                if (destination.state !== "not-installed")
+                    await rm(destination.path, { recursive: true, force: true });
+                await mkdir(path.dirname(destination.path), { recursive: true });
+                await cp(bundledSkillPath, destination.path, { recursive: true });
+                output.log(formatInstallSuccess(destination, { alreadyInstalled: false, color }));
+            }
+        }
+        else if (destination.state === "not-installed") {
+            output.log(`${destination.displayName}: not installed at ${destination.path}`);
+        }
+        else {
+            await rm(destination.path, { recursive: true, force: true });
+            output.log(`${destination.displayName}: uninstalled from ${destination.path}`);
+        }
+    }
+    return states.map(({ agent, path: destinationPath, state }) => ({ agent, path: destinationPath, state }));
+}

package/build/src/commands/help.js

@@ -1,6 +1,7 @@
 /**
  * Help command handler
  */
+import { CUA_MODELS } from '../core/cua-models.js';
 /**
  * Handle /help command
  * @param {string} args - Command arguments
@@ -32,7 +33,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  --session-mode <mode>  Browser session mode for web runs: persistent or fresh' });
     addOutput({ type: 'info', text: '  --config <file>        Headless execution JSON config for prompt parity' });
     addOutput({ type: 'info', text: '  --llm-provider <mode>  Headless AI provider: loadmill or openai' });
-    addOutput({ type: 'info', text: '  --cua-model <model>    Headless CUA model override: gpt-5.4, loadmill-smart, loadmill-beacon, or gpt-5.4-mini' });
+    addOutput({ type: 'info', text: `  --cua-model <model>    Headless CUA model override: ${CUA_MODELS.join(', ')}` });
     addOutput({ type: 'info', text: '  --aim-assist <mode>    Headless Aim Assist mode: off, smart, or always' });
     addOutput({ type: 'info', text: '  --context <file>       Optional app context file injected into execution runs' });
     addOutput({ type: 'info', text: '  --no-context           Disable app context for headless execution' });

package/build/src/core/cua-models.js

@@ -1,9 +1,6 @@
 export const DEFAULT_OPENAI_CUA_MODEL = "gpt-5.4";
 export const DEFAULT_LOADMILL_CUA_MODEL = "loadmill-smart";
 export const DEFAULT_CUA_MODEL = DEFAULT_LOADMILL_CUA_MODEL;
-export const OPENAI_CUA_MODELS = ["gpt-5.4", "gpt-5.4-mini"];
-export const LOADMILL_CUA_MODELS = [DEFAULT_LOADMILL_CUA_MODEL, "loadmill-beacon"];
-export const CUA_MODELS = ["gpt-5.4", "loadmill-smart", "loadmill-beacon", "gpt-5.4-mini"];
 export const CUA_MODEL_OPTIONS = Object.freeze([
     Object.freeze({
         id: "loadmill-smart",
@@ -20,20 +17,34 @@ export const CUA_MODEL_OPTIONS = Object.freeze([
         label: "Loadmill - Beacon",
     }),
     Object.freeze({
-        id: "gpt-5.4",
+        id: "gpt-5.6-terra",
         providerMode: "openai",
         providerLabel: "OpenAI",
-        name: "GPT-5.4",
-        label: "OpenAI GPT-5.4",
+        name: "GPT-5.6 Terra",
+        label: "OpenAI GPT-5.6 Terra",
+    }),
+    Object.freeze({
+        id: "gpt-5.6-luna",
+        providerMode: "openai",
+        providerLabel: "OpenAI",
+        name: "GPT-5.6 Luna",
+        label: "OpenAI GPT-5.6 Luna",
     }),
     Object.freeze({
-        id: "gpt-5.4-mini",
+        id: "gpt-5.4",
         providerMode: "openai",
         providerLabel: "OpenAI",
-        name: "GPT-5.4 mini",
-        label: "OpenAI GPT-5.4 mini (faster)",
+        name: "GPT-5.4",
+        label: "OpenAI GPT-5.4",
     }),
 ]);
+export const CUA_MODELS = Object.freeze(CUA_MODEL_OPTIONS.map((option) => option.id));
+export const OPENAI_CUA_MODELS = Object.freeze(CUA_MODEL_OPTIONS
+    .filter((option) => option.providerMode === "openai")
+    .map((option) => option.id));
+export const LOADMILL_CUA_MODELS = Object.freeze(CUA_MODEL_OPTIONS
+    .filter((option) => option.providerMode === "loadmill")
+    .map((option) => option.id));
 const VALID_CUA_MODELS = new Set(CUA_MODELS);
 const OPENAI_CUA_MODEL_SET = new Set(OPENAI_CUA_MODELS);
 const LOADMILL_CUA_MODEL_SET = new Set(LOADMILL_CUA_MODELS);

package/build/src/core/droid-cua-run-usage.js

@@ -2,16 +2,22 @@ const TOKENS_PER_MILLION = 1_000_000;
 const OPENAI_GPT_5_4_PRICING = Object.freeze({
     inputPerMillionUsd: 2.5,
 });
-const OPENAI_GPT_5_4_MINI_PRICING = Object.freeze({
-    inputPerMillionUsd: 0.75,
+const OPENAI_GPT_5_6_TERRA_PRICING = Object.freeze({
+    inputPerMillionUsd: 2.5,
+});
+const OPENAI_GPT_5_6_LUNA_PRICING = Object.freeze({
+    inputPerMillionUsd: 1,
 });
 const MODEL_PRICING = Object.freeze({
+    "gpt-5.6-terra": Object.freeze({
+        ...OPENAI_GPT_5_6_TERRA_PRICING,
+    }),
+    "gpt-5.6-luna": Object.freeze({
+        ...OPENAI_GPT_5_6_LUNA_PRICING,
+    }),
     "gpt-5.4": Object.freeze({
         ...OPENAI_GPT_5_4_PRICING,
     }),
-    "gpt-5.4-mini": Object.freeze({
-        ...OPENAI_GPT_5_4_MINI_PRICING,
-    }),
     // Loadmill Smart currently routes to GPT-5.4 behind the Loadmill LLM gateway.
     // Keep this explicit so pricing can be updated here if the backing model changes.
     "loadmill-smart": Object.freeze({
@@ -32,8 +38,11 @@ export function normalizeDroidCuaCostModel(model) {
     if (typeof model !== "string") {
         return null;
     }
-    if (model === "gpt-5.4-mini" || model.startsWith("gpt-5.4-mini-")) {
-        return "gpt-5.4-mini";
+    if (model === "gpt-5.6-terra" || model.startsWith("gpt-5.6-terra-")) {
+        return "gpt-5.6-terra";
+    }
+    if (model === "gpt-5.6-luna" || model.startsWith("gpt-5.6-luna-")) {
+        return "gpt-5.6-luna";
     }
     if (model === "gpt-5.4" || model.startsWith("gpt-5.4-")) {
         return "gpt-5.4";

package/build/src/core/runtime-config.js

@@ -90,11 +90,8 @@ export function inferLlmProviderModeFromCredentials(credentials = {}) {
 }
 export function resolveGatewayCuaModelAlias({ cuaModel } = {}) {
     const normalizedCuaModel = resolveCuaModel(cuaModel);
-    if (normalizedCuaModel === "loadmill-beacon") {
-        return LOADMILL_MODEL_ALIASES.BEACON;
-    }
-    return normalizedCuaModel === "gpt-5.4-mini"
-        ? LOADMILL_MODEL_ALIASES.FAST
+    return normalizedCuaModel === "loadmill-beacon"
+        ? LOADMILL_MODEL_ALIASES.BEACON
         : LOADMILL_MODEL_ALIASES.SMART;
 }
 export function resolveEffectiveCuaModel({ llmProviderMode = null, cuaModel = null, } = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loadmill/droid-cua",
-  "version": "2.23.0",
+  "version": "2.24.0",
   "description": "AI-powered Android testing agent using OpenAI's computer-use model and ADB",
   "main": "build/index.js",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "build/**/*",
     "bin/**/*",
+    "skill/**/*",
     "README.md",
     "LICENSE"
   ],

package/skill/droid-cua/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: droid-cua
+description: Write, run, monitor, and troubleshoot Droid CUA mobile and web tests. Use when an agent needs to onboard @loadmill/droid-cua, configure Loadmill authentication, discover Android devices or AVDs, prepare iOS simulators or local browsers, author or revise .dcua tests and project context, run tests locally or on supported cloud devices, analyze reports and debug artifacts, distinguish test failures from product bugs, or perform guarded test healing.
+---
+
+# Droid CUA
+
+Use the existing `droid-cua` CLI and repository files. Do not invent commands, flags, or product capabilities.
+
+## Workflow
+
+1. Inspect the active test project before creating files. Find existing `.dcua` tests, `context.md`, `test-data.md`, `.secrets`, `.env`, and `ci/droid-cua.json` without reading secret values. Do not search other projects or the user's home directory for credentials.
+2. Determine the requested platform and target from the task or project. Ask the user only when the choice is unclear.
+3. Check authentication and environment readiness before the first run. Read [project-and-auth.md](references/project-and-auth.md) for project boundaries and token handling. Read [onboarding-and-troubleshooting.md](references/onboarding-and-troubleshooting.md) when setup, dependency, device, simulator, browser, or connection work is needed.
+4. Author or update the smallest useful test. Read [authoring-tests.md](references/authoring-tests.md) before changing `.dcua`, context, test data, secrets, or config.
+5. Run the narrowest relevant test and monitor it to completion. Read [running-and-healing.md](references/running-and-healing.md) for commands, targets, artifacts, failure classification, and guarded healing.
+6. Report the outcome, evidence paths, changes made, and whether the failure belongs to the test, environment, or product.
+
+## Safety
+
+- Never print, open, or echo secret values. Check only whether required keys are configured.
+- Never search for credentials outside the active test project or source another project's `.env` file.
+- Get approval before installing dependencies, running `sudo`, accepting licenses, or changing system configuration.
+- During setup, do not create or edit user tests. Rerun only the failed readiness check, then resume the original task.
+- During healing, edit only `.dcua`, `context.md`, `test-data.md`, or Droid CUA config. Never modify application code under the guise of healing a test.
+- Never weaken or remove an assertion merely to make a failing run pass.
+- Make one minimal change and run the affected test again. Stop after two edit/rerun cycles and present the evidence.
+- Stop immediately when evidence indicates a likely application regression; do not rewrite the test to match broken behavior.
+- Gracefully allow cloud runs to finish cleanup. Avoid terminating a metered device session unless necessary.
+
+## Operating principles
+
+- Prefer an existing project convention over creating a parallel structure.
+- Prefer headless runs for agent work because they are observable and return deterministic exit codes.
+- Use explicit, user-observable outcomes in tests rather than implementation details or coordinates.
+- Diagnose the first divergence between the instruction and observed behavior before changing anything.

package/skill/droid-cua/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Droid Cua"
+  short_description: "Write, run, monitor, and troubleshoot Droid CUA tests"
+  icon_small: "./assets/droid-cua-app-icon.png"
+  icon_large: "./assets/droid-cua-app-icon.png"
+  brand_color: "#1895F7"

package/skill/droid-cua/references/authoring-tests.md

@@ -0,0 +1,39 @@
+# Authoring tests
+
+## Inspect first
+
+Find nearby `.dcua` tests and project files before writing. Match their directory layout, naming, vocabulary, starting state, and config conventions. Do not open `.env` or `.secrets`.
+
+## Write `.dcua` instructions
+
+- Put one clear instruction or assertion on each non-empty line.
+- Describe visible UI intent, not coordinates, selectors, implementation details, or model strategy.
+- Prefer a high-level business intent when `context.md` makes the flow unambiguous. Do not translate every tap and keystroke into a brittle micro-script.
+- Break an instruction down only when the agent demonstrably needs help finding a control or completing part of the flow.
+- State the starting condition when it is not guaranteed by the environment.
+- Use explicit assertions for important outcomes. Prefer stable visible facts such as a screen title, confirmation message, changed value, or navigation result.
+- Use exact visible labels when naming controls or outcomes.
+- Keep each test focused on one behavior. Split unrelated flows.
+- Use `//` comments sparingly for human context; comments are not executed.
+- Never include secret values in the test.
+
+Example:
+
+```text
+Sign in using the USER_EMAIL and USER_PASSWORD secrets.
+Assert that the Home screen is visible and shows the signed-in account.
+```
+
+Use the secret key names that exist in `.secrets`; do not inspect their values. If key discovery is necessary, filter the file so only keys reach output, for example `sed -n 's/^\([^#][^=]*\)=.*/\1/p' .secrets`. If a required key is absent, ask the user to add it without sharing its value.
+
+## Put knowledge in the right place
+
+- Put durable product behavior and terminology in `context.md`, not repeated in every test.
+- Put non-secret reusable people, accounts, products, and scenario combinations in `test-data.md`.
+- Put credentials and sensitive values in `.secrets`.
+- Put reproducible headless settings in `ci/droid-cua.json`.
+- Keep environment and provider credentials in `.env` or the shell/CI secret store.
+
+Use `--scenario "<goal>" --test-data <path>` only when the user wants generated permutations or cases. A normal `.dcua` run does not automatically consume `test-data.md`.
+
+After editing, show the user the test instructions and explain any new context, data keys, or secret keys required. Never show secret values.

package/skill/droid-cua/references/onboarding-and-troubleshooting.md

@@ -0,0 +1,74 @@
+# Onboarding and troubleshooting
+
+Follow the Desktop Device Setup Wizard sequence: choose a platform, run checks, discover/connect a target, verify runtime access during the requested run, then continue the original task. Run authentication as the separate first preflight described in `project-and-auth.md`.
+
+Do not create or modify user test files merely to perform setup. Get approval before installing software, changing system configuration, running `sudo`, or accepting a license. After remediation, rerun only the failed check.
+
+## Android
+
+Resolve `adb` and `emulator` from `ANDROID_HOME`, `ANDROID_SDK_ROOT`, the macOS default `~/Library/Android/sdk`, the Windows default `%LOCALAPPDATA%\Android\Sdk`, then `PATH`. Respect explicit `DROID_CUA_ANDROID_ADB_PATH` and `DROID_CUA_ANDROID_EMULATOR_PATH` overrides.
+
+Run these checks:
+
+```sh
+adb version
+emulator -list-avds
+adb devices
+```
+
+- `adb` is blocking.
+- The emulator CLI and existence of an AVD are individually non-blocking.
+- Target availability is blocking and passes when `adb devices` contains a `device` entry or `emulator -list-avds` contains a launchable AVD.
+- For `unauthorized`, ask the user to accept the computer authorization prompt on the device.
+- For `offline`, reconnect the device or restart ADB, then retry.
+- If nothing is available, guide the user to connect a device or create an AVD in Android Studio Device Manager.
+
+Use `--avd adb:<serial>` for an attached target and `--avd avd:<name>` to launch an AVD.
+
+## iOS
+
+Local iOS execution requires macOS. Run checks in this order:
+
+```sh
+xcrun --version
+xcode-select -p
+xcodebuild -license check
+xcodebuild -checkFirstLaunchStatus
+node --version
+npm --version
+appium --version
+appium driver list --installed
+xcrun simctl list devices --json
+```
+
+Require `xcode-select -p` to point to an `/Xcode*.app/Contents/Developer` path, an installed XCUITest driver, and at least one available iPhone simulator. A booted simulator is helpful but not blocking.
+
+Offer only the relevant remediation, with approval:
+
+```sh
+sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
+sudo xcodebuild -license accept
+sudo xcodebuild -runFirstLaunch
+npm install -g appium
+appium driver install xcuitest
+```
+
+Use `--platform ios --avd "<simulator name>"` for the run.
+
+## Web
+
+Droid CUA automatically discovers Chrome or Edge on macOS and Windows. Check the standard application locations, then run the requested test with `--target web --browser <chrome|edge> --session-mode fresh`. A successful Playwright launch is the runtime verification; do not create a persistent setup-only test.
+
+On Linux, automatic installed-browser discovery is not currently supported. Do not claim that a PATH-installed browser will be found.
+
+## Cloud targets
+
+For LambdaTest, require `LAMBDATEST_USERNAME`, `LAMBDATEST_ACCESS_KEY`, a device name, OS version, and `.apk` or `.ipa`. The CLI uploads the app for each run.
+
+For AWS Device Farm, require `AWS_DEVICE_FARM_ACCESS_KEY_ID`, `AWS_DEVICE_FARM_SECRET_ACCESS_KEY`, and `AWS_DEVICE_FARM_PROJECT_ARN`. Discover targets with:
+
+```sh
+droid-cua --device-source aws-device-farm --list-devices
+```
+
+Do not document BrowserStack CLI runs; BrowserStack is not consistently exposed by the current CLI.

package/skill/droid-cua/references/project-and-auth.md

@@ -0,0 +1,38 @@
+# Project files and authentication
+
+## Project files
+
+- `.dcua`: executable test instructions. Each non-empty line is one instruction; `//` begins a comment.
+- `context.md`: durable knowledge about product terminology, screens, navigation, and behavior. Pass it with `--context`, or reference it from `ci/droid-cua.json`.
+- `test-data.md`: non-secret entities and scenario inputs. It is used with `--scenario` and `--test-data`; it is not automatically loaded by every normal test run.
+- `.secrets`: dotenv-style values that Droid CUA may type into the tested application. The model receives the keys, not the resolved values. Headless execution loads this file from the current working directory; `--secrets` overrides it.
+- `.env`: infrastructure credentials and runtime environment variables loaded from the current working directory, including `LOADMILL_API_TOKEN`.
+- `ci/droid-cua.json`: optional checked-in headless config. Paths inside it are relative to the config file.
+- `logs/`: structured JSONL and screenshot artifacts created by `--debug`.
+- HTML reports: self-contained evidence produced by `--report`.
+
+Keep `.env` and `.secrets` out of version control. Use `git check-ignore -q .env` and `git check-ignore -q .secrets` to check ignore coverage without opening either file.
+
+## Loadmill authentication
+
+Loadmill is the default LLM provider. Before a run, check only for presence:
+
+```sh
+test -n "${LOADMILL_API_TOKEN:-}" || grep -Eq '^LOADMILL_API_TOKEN=.+$' .env 2>/dev/null
+```
+
+Run this check from the active test project's working directory. Do not print the variable, run `env`, open `.env`, or ask the user to paste the token. Do not search parent directories, sibling repositories, the user's home directory, or the Droid CUA source repository for credentials.
+
+If it is missing, instruct the user to:
+
+1. Sign in at <https://app.loadmill.com>.
+2. Open **Settings → Security**.
+3. Create an API token with a description such as `Droid CUA CLI`.
+4. Copy it when shown; Loadmill shows it once.
+5. Ensure `.env` is ignored by version control before storing a project token; add `.env` to `.gitignore` if needed.
+6. Save it as `LOADMILL_API_TOKEN=...` in the active test project's `.env`, a shell environment variable, or a CI secret.
+7. Confirm when configuration is complete, without sharing the value.
+
+Do not create or populate the token value for the user. Do not copy a token from another file or source another project's `.env`. Sourcing an unrelated file can import development endpoints, proxy settings, and unrelated secrets. When the active project's `.env` contains the key, run `droid-cua` normally from that project; the CLI loads that file automatically.
+
+If the user explicitly selects direct OpenAI access, use `--llm-provider openai` with one of the supported OpenAI CUA models: `gpt-5.6-terra`, `gpt-5.6-luna`, or `gpt-5.4`. Check only for the presence of `OPENAI_API_KEY`. If it is missing, instruct the user to create an API key in their OpenAI account and save it in the active project's gitignored `.env`, their shell environment, or a CI secret. Apply the same secret-handling rules: never request, print, inspect, copy, or source the key. Do not silently switch providers to bypass missing Loadmill authentication.

package/skill/droid-cua/references/running-and-healing.md

@@ -0,0 +1,70 @@
+# Running, monitoring, and guarded healing
+
+## Construct the run
+
+Prefer a single test before a directory or scenario run. Preserve an existing provider/model choice in `ci/droid-cua.json`; otherwise use the Loadmill provider. Use Loadmill Smart as the recommended default, or Loadmill Beacon when the user prioritizes faster, lower-cost execution:
+
+```sh
+# Recommended default
+--llm-provider loadmill --cua-model loadmill-smart
+
+# Faster, lower-cost option
+--llm-provider loadmill --cua-model loadmill-beacon
+```
+
+Both Loadmill models require `LOADMILL_API_TOKEN`. Do not switch between Smart and Beacon silently; preserve the project's model or explain the speed/cost tradeoff and follow the user's choice. If the user chooses direct OpenAI access instead, require `OPENAI_API_KEY` and use `--llm-provider openai` with one of `gpt-5.6-terra`, `gpt-5.6-luna`, or `gpt-5.4`. Do not mix a provider with another provider's model, silently switch providers, or override an existing project choice without explaining it.
+
+Include `--report reports/<test-name>.html` for normal test runs unless the user opts out. Prefer an explicit filename over a directory so the result is easy to locate. Add `--debug` when diagnosis may be needed.
+
+```sh
+# Attached Android device or running emulator
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --avd adb:<serial> --instructions tests/example.dcua --context tests/context.md --debug --report reports/example.html
+
+# Launchable Android AVD
+droid-cua --avd avd:<avd-name> --instructions tests/example.dcua --config ci/droid-cua.json --debug --report reports/example.html
+
+# iOS Simulator
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --platform ios --avd "<simulator-name>" --instructions tests/example.dcua --debug --report reports/example.html
+
+# Local web
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --target web --browser chrome --session-mode fresh --instructions tests/example.dcua --debug --report reports/example.html
+
+# LambdaTest
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --device-source lambdatest --platform android --device-name "<name>" --os-version "<version>" --app <app.apk> --instructions tests/example.dcua --debug --report reports/example.html
+
+# AWS Device Farm
+droid-cua --llm-provider loadmill --cua-model loadmill-smart --device-source aws-device-farm --platform android --device-name "<name>" --os-version "<version>" --app <app.apk> --instructions tests/example.dcua --debug --report reports/example.html
+
+# Direct OpenAI alternative
+droid-cua --llm-provider openai --cua-model gpt-5.4 --avd adb:<serial> --instructions tests/example.dcua --context tests/context.md --debug --report reports/example.html
+```
+
+Use `.ipa` and `--platform ios` for supported cloud iOS runs. Preserve existing config flags rather than replacing them with defaults.
+
+## Monitor and collect evidence
+
+Remain attached until the command exits and cloud cleanup finishes. Read terminal progress as it appears; do not treat a long model step as success or failure before completion.
+
+- Exit `0`: all requested tests passed.
+- Exit `1`: configuration, connection, execution, or assertion failure.
+- Exit `130`: interrupted run.
+- `--debug`: writes structured execution JSONL and adjacent screenshots under `logs/`.
+- `--report`: writes a self-contained HTML report. Prefer an explicit `.html` file path such as `reports/example.html` so the evidence location is unambiguous.
+
+After the run, verify that the report exists and resolve its absolute path. Open it for the user when the agent environment supports local-file opening and policy permits; otherwise provide a clickable local-file link or the absolute path so the user can open it directly.
+
+Report the outcome, failing instruction and first divergence when applicable, relevant error text, screenshot/debug/report paths, target, provider/model, and command with secret values omitted.
+
+## Classify the first divergence
+
+1. **Setup or authentication**: missing/invalid provider credential, dependency, license, browser, or executable. Return to onboarding and rerun only the failed check.
+2. **Target connectivity**: no device, unauthorized/offline ADB state, unavailable simulator, cloud credential/device/app problem, or lost session. Restore the same target, then rerun.
+3. **Test ambiguity or stale test knowledge**: instruction has multiple interpretations, relies on an unstable label, lacks a starting condition, or context contradicts the visible product. A minimal test/context correction is allowed.
+4. **Application regression**: the app crashes, displays an error, violates an explicit requirement, or consistently fails a stable assertion after correct setup. Stop and report a bug with evidence.
+5. **Transient execution**: temporary network, service, model, or timing failure without evidence of a deterministic product/test issue. Retry the unchanged targeted test once.
+
+## Guarded healing
+
+Before editing, state the classification and evidence. Change only `.dcua`, `context.md`, `test-data.md`, or Droid CUA config. Never edit app code, delete coverage, loosen the expected outcome, or add broad waits simply to obtain green output.
+
+Make one minimal change, explain why it corrects the test rather than hides a product defect, and rerun only the affected test. Allow at most two edit/rerun cycles. If it still fails, stop with the original and final evidence, changes attempted, and recommended owner/action.