@ishlabs/cli 0.24.1 → 0.25.0

package/dist/commands/ask.js

@@ -436,15 +436,15 @@ Picks come back with a \`pick_confidence\` (0..1) score per participant when
     // error rather than a transient failure.
     ask
         .command("dispatch")
-        .description("Dispatch a draft ask — bills credits and starts the round")
+        .description("Dispatch a draft ask — draws credits and starts the round")
         .argument("[id]", "Ask alias or UUID (defaults to active ask)")
         .option("--ask <id>", "Ask ID; alternative to positional argument")
         .option("--wait", "Wait until the first round completes (or errors)")
         .option("--timeout <s>", "Wait timeout in seconds (default 300)")
         .addHelpText("after", `
 Use after \`ish ask create --no-dispatch\` to start a draft once the user has
-reviewed it. The dispatch is BILLABLE — credits are charged when responses
-land, the same as a normal create.
+reviewed it. Dispatch draws credits as responses land, the same as a normal
+create. This is the expected way to run an ask — go ahead and dispatch.
 
 Examples:
   # Dispatch the active draft and wait for results:

package/dist/commands/iteration.js

@@ -383,7 +383,7 @@ Concept pages: ish docs get-page concepts/iteration
         // Media image
         .option("--image-urls <urls>", "Comma-separated image URLs or local file paths — image modality")
         // Shared media
-        .option("--title <title>", "Content title — media modalities")
+        .option("--title <title>", "Content title shown to participants (the leading headline they read) — media modalities")
         .option("--mime-type <type>", "MIME type (e.g. video/mp4) — media modalities")
         // Copy/caption
         .option("--copy-text <text>", "Ad copy or social post caption (or @filepath) — ads & social posts")

package/dist/commands/study-analyze.js

@@ -81,7 +81,7 @@ export function attachStudyAnalyzeCommands(study) {
     study
         .command("analyze")
         .description("Trigger an AI summary + key-insights analysis for a study. " +
-        "First analysis per study is free; subsequent runs cost 10 credits.")
+        "First analysis per study is included; subsequent runs draw 10 credits.")
         .argument("[id]", "Study ID (defaults to active study)")
         .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
         .option("--wait", "Poll until the run reaches completed or failed")

package/dist/commands/study-run.js

@@ -33,8 +33,8 @@ function parseMaxInteractions(value) {
 /**
  * Default cap the CLI sends when neither `--max-interactions` nor the
  * iteration carries its own value. Picked to match the frontend's
- * conservative interactive launchers and to prevent runaway spend when an
- * iteration runs against a broken or non-responsive surface — without a
+ * conservative interactive launchers and to prevent runaway credit draw when
+ * an iteration runs against a broken or non-responsive surface — without a
  * cap, a stuck participant can rack up hundreds of steps before the SDK gives
  * up.
  */
@@ -264,6 +264,34 @@ function readIterationDetails(details) {
         ...(typeof details.title === "string" && { title: details.title }),
     };
 }
+/**
+ * Normalize a platform string for matching. "web", "browser", and unset all
+ * mean the default browser path; "android"/"ios" are native. Lets `--platform
+ * web` match a "browser" iteration (and vice-versa) without false mismatches.
+ */
+function normalizePlatform(platform) {
+    const p = (platform ?? "").toLowerCase();
+    if (p === "" || p === "web" || p === "browser")
+        return "browser";
+    return p;
+}
+/**
+ * The local platform the user explicitly requested via flags, before any
+ * iteration is picked: --platform, or inferred from --app's extension
+ * (.apk → android, .app → ios). Undefined when neither is set (no preference →
+ * don't filter iterations by platform). The iteration's stored platform is
+ * deliberately NOT consulted here — it's what we're selecting against.
+ */
+function requestedLocalPlatform(opts) {
+    if (opts.platform)
+        return opts.platform;
+    const app = opts.app?.toLowerCase();
+    if (app?.endsWith(".apk"))
+        return "android";
+    if (app?.endsWith(".app"))
+        return "ios";
+    return undefined;
+}
 export function attachStudyRunCommands(study) {
     // --- Primary: `study run` ---
     const studyRun = study
@@ -294,6 +322,8 @@ export function attachStudyRunCommands(study) {
         .option("--devtools", "Open Chrome DevTools (local mode only)")
         .option("--debug", "Enable detailed debug logging to stderr and ~/.ish/local-sim.log")
         .option("--parallel <n>", "Run N participants in parallel (local mode only, default: all)")
+        .option("--platform <platform>", "Local target platform: 'web' (Playwright), 'android' (adb emulator), or 'ios' (simctl+idb simulator). Defaults to the iteration's platform.")
+        .option("--app <path>", "Native local mode: path to an .apk (android) / .app (ios) to install, or an installed package/bundle id to launch. The extension implies --platform.")
         .addHelpText("after", `
 Note: --workspace and --study are optional if you have set active context
   via \`ish workspace use <alias>\` and \`ish study use <alias>\`.
@@ -326,7 +356,7 @@ Examples:
   $ ish study run --config c-c3c
 
   # Cap interactions per participant (default 20 — pass higher to allow deeper
-  # exploration, lower to cap spend on a known-broken surface):
+  # exploration, lower to cap credit draw on a known-broken surface):
   $ ish study run --max-interactions 30
 
   # Block until all simulations finish (or timeout):
@@ -412,8 +442,13 @@ Examples:
             if (!study.assignments || study.assignments.length === 0) {
                 throw new Error("Study has no assignments. Add tasks with --assignments when creating the study, or use `ish study generate`.");
             }
-            // Step 1: Pick iteration (explicit --iteration, or latest on study)
+            // Step 1: Pick iteration (explicit --iteration, or latest on study).
+            // When --platform / --app requests a local platform, select the
+            // iteration whose details.platform matches — otherwise a multi-platform
+            // study (e.g. an android AND an ios iteration) would silently run the
+            // latest, which may be the wrong platform.
             const iterations = study.iterations || [];
+            const wantPlatform = opts.local ? requestedLocalPlatform(opts) : undefined;
             let iteration;
             if (opts.iteration) {
                 const wantedId = resolveId(opts.iteration);
@@ -421,6 +456,25 @@ Examples:
                 if (!iteration) {
                     throw new Error(`Iteration ${opts.iteration} not found on this study.`);
                 }
+                // An explicit --iteration whose platform contradicts --platform is a
+                // footgun (you'd drive the wrong device); refuse rather than guess.
+                if (wantPlatform) {
+                    const itPlatform = readIterationDetails(iteration.details).platform;
+                    if (normalizePlatform(itPlatform) !== normalizePlatform(wantPlatform)) {
+                        throw new Error(`--platform ${wantPlatform} but iteration ${opts.iteration} is platform ` +
+                            `'${itPlatform ?? "browser"}'. Pass the matching iteration or drop --platform.`);
+                    }
+                }
+            }
+            else if (wantPlatform) {
+                // Latest iteration whose platform matches the requested one.
+                const matching = iterations.filter((it) => normalizePlatform(readIterationDetails(it.details).platform) === normalizePlatform(wantPlatform));
+                if (matching.length === 0) {
+                    const available = [...new Set(iterations.map((it) => normalizePlatform(readIterationDetails(it.details).platform)))].join(", ") || "none";
+                    throw new Error(`No ${wantPlatform} iteration on this study (platforms present: ${available}). ` +
+                        `Create one with \`ish iteration create --study ${resolvedStudy} ...\`, or pass --iteration.`);
+                }
+                iteration = matching[matching.length - 1];
             }
             else if (iterations.length > 0) {
                 iteration = iterations[iterations.length - 1];
@@ -691,6 +745,21 @@ Examples:
             // by reusing the iteration's existing Conversation rows or by
             // calling pair-batch.
             let pairConversationIds = [];
+            // Resolve the local target platform ONCE so participant-create and the
+            // local-sim dispatch agree. Precedence: --platform flag > --app
+            // extension (.apk → android, .app → ios) > iteration's stored platform
+            // > browser. Used to set participant.platform (so the backend's native
+            // trigger is driven primarily by the participant, not just the
+            // empty-tree fallback) and to pick the device in the local loop.
+            const platformFromApp = opts.app?.toLowerCase().endsWith(".apk")
+                ? "android"
+                : opts.app?.toLowerCase().endsWith(".app")
+                    ? "ios"
+                    : undefined;
+            const resolvedPlatform = opts.platform
+                ?? platformFromApp
+                ?? detailsView.platform
+                ?? "browser";
             if (isPair && pairConfig) {
                 // Pair-mode flow mirrors the MCP (`ish-mcp` `_run_pair_mode`):
                 //   1. If the iteration already carries `conversations[]` from a
@@ -782,7 +851,7 @@ Examples:
                     participant_type: "ai",
                     status: "draft",
                     ...(opts.language && { language: opts.language }),
-                    ...(!isMedia && !isChat && { platform: detailsView.platform || "browser" }),
+                    ...(!isMedia && !isChat && { platform: resolvedPlatform }),
                 }));
                 log(`Creating ${participantInputs.length} participant${participantInputs.length > 1 ? "s" : ""}...`);
                 const batchResult = await client.post(`/iterations/${iterationId}/participants/batch`, { participants: participantInputs }, { timeout: dispatchTimeoutMs });
@@ -814,6 +883,8 @@ Examples:
                     devtools: opts.devtools,
                     debug: opts.debug,
                     parallel: opts.parallel ? parseInt(opts.parallel, 10) : undefined,
+                    platform: resolvedPlatform,
+                    ...(opts.app && { appPath: opts.app }),
                     quiet: globals.quiet,
                     json: globals.json,
                 });
@@ -1042,14 +1113,11 @@ Examples:
                     }, true);
                 }
                 else {
-                    for (let i = 0; i < simResults.length; i++) {
-                        const participant = createdParticipants[i];
-                        const personName = participant?.person?.name || "Unknown";
-                        log(`  ${personName.padEnd(24)} QUEUED`);
-                    }
+                    const studyAlias = tagAlias(ALIAS_PREFIX.study, resolvedStudy);
+                    const n = createdParticipants.length;
+                    log(`Dispatched ${n} participant${n > 1 ? "s" : ""} — run \`ish study results ${studyAlias}\` for results (or \`ish study poll --study ${studyAlias}\` / --wait to track progress).`);
                     const url = getWebUrl(globals, `/${resolvedWorkspace}/${resolvedStudy}/timeline`);
-                    log(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
-                    log(`Run \`ish study poll --study ${resolvedStudy}\` (or --wait next time) to check progress.`);
+                    log(`  ${terminalLink(url, "Open in browser ↗")}`);
                 }
                 return;
             }

package/dist/commands/study.js

@@ -113,7 +113,7 @@ Concept pages: ish docs get-page concepts/study
         .requiredOption("--name <name>", "Study name")
         .option("--description <description>", "Study description")
         .option("--modality <modality>", "Study modality (interactive, video, audio, text, image, document, chat)")
-        .option("--content-type <type>", "Content type (per-modality enum — see 'Content types by modality' below). Not used for interactive / chat.")
+        .option("--content-type <type>", "Content type (per-modality enum — see 'Content types by modality' below). Changes how --title is presented to participants (e.g. content-type email renders --title as the Subject: line). Not used for interactive / chat.")
         .option("--assignment <name:instructions>", "Assignment as 'Name:Instructions' (repeatable)", collectRepeatable, [])
         .option("--assignments-file <path>", "JSON file with assignments array")
         .option("--assignments <json>", "Inline JSON array of assignments (escape hatch)")
@@ -124,7 +124,7 @@ Concept pages: ish docs get-page concepts/study
         .option("--screen-format <format>", "Screen format for interactive iterations: desktop (default) or mobile_portrait (hyphen/underscore variants accepted)")
         .option("--content-url <url>", "Public URL of the media file. Creates iteration A inline (video, audio, document modalities). For local files, use the 2-step `iteration create` flow.")
         .option("--image-urls <urls>", "Comma-separated public image URLs. Creates iteration A inline (image modality). For local files, use the 2-step `iteration create` flow.")
-        .option("--title <title>", "Content title (text + media modalities — image, video, audio, document; optional). Not used for interactive / chat.")
+        .option("--title <title>", "Participant-facing content title — the headline participants read before the body (text + media modalities — image, video, audio, document; optional). With --content-type email it becomes the email Subject: line. Not an internal label. Not used for interactive / chat.")
         .option("--segmentation-json <json>", "Segmentation JSON for the inline iteration A — time_based {intervals_seconds, labels?}, section_based {sections[{name,label,...}]}, or page_based {} (text + media). section_based sections are SEMANTIC: group related paragraphs into a few coherent sections (a long article is usually 3-6 sections, not one per paragraph). Lets one `study create` build a complete segmented iteration — no separate `iteration create` needed.")
         .option("--content-config-json <json>", "Content-config JSON for the inline iteration A (early_termination, selected_segment_indices) — text + media.")
         .option("--content-html <html>", "HTML version of the text, or @filepath — text modality (email rendering)")
@@ -239,6 +239,9 @@ Examples:
 
 Content types by modality (source: VALID_CONTENT_TYPES in src/lib/types.ts; interactive + chat omitted — they don't take --content-type):
 ${describeContentTypes()}
+  The content type also shapes how --title is rendered to participants: with
+  content-type email, --title becomes the email Subject: line; otherwise it
+  reads as the leading headline of the content.
 
 Tips:
   Use \`--get <path>\` to capture a single value (e.g. \`--get id\`),
@@ -310,11 +313,12 @@ Next: configure a run with \`ish iteration create --study <id>\`,
                 }
                 normalizedScreenFormat = normalized;
             }
-            // Pattern G.2: --title is metadata, not content. The backend
-            // accepts it on text + media modalities (see
-            // `buildIterationDetails` in iteration.ts). Reject it only on
-            // shapes that have no title field — interactive (URL only) and
-            // chat (endpoint config carries its own metadata).
+            // --title is participant-facing content: the backend renders it as a
+            // leading headline participants read before the body (and as the email
+            // Subject: line when content-type is email). It only exists on text +
+            // media modalities (see `buildIterationDetails` in iteration.ts), so
+            // reject it on shapes that have no title field — interactive (URL only)
+            // and chat (endpoint config carries its own configuration).
             if (opts.title !== undefined
                 && opts.contentText === undefined
                 && opts.contentUrl === undefined

package/dist/lib/alias-store.js

@@ -129,7 +129,7 @@ const HYDRATE_HINT = {
     // alias map at ~/.ish/aliases.json carries any sources the CLI has
     // touched in this session.
     ps: "ish source upload <file>  # or `cat ~/.ish/aliases.json | grep ^ps-` to recover prior aliases",
-    pt: "ish participant get <participant-id>",
+    pt: "ish study participant <participant-id>",
     c: "ish config list",
     a: "ish ask list",
     r: "ish ask get <ask-id>",

package/dist/lib/api-client.d.ts

@@ -48,6 +48,8 @@ export declare class ApiClient {
         screenshot_url?: string;
         location_name: string;
         screen_format?: string;
+        full_page_screenshot_base64?: string;
+        platform?: string;
     }): Promise<{
         frame_version_id: string;
     }>;

package/dist/lib/docs.js

@@ -339,7 +339,7 @@ pick was wrong.
 - \`guides/slicing-results\` — filter / project \`study results\` by frame,
   segment, turn, sentiment, assignment, step.
 - \`reference/billing-limits\` — \`maxStudiesPerProduct\` cap on study creation.
-- \`reference/credits\` — per-run credit cost & how to preview before dispatch.
+- \`reference/credits\` — per-run credit draw & how to preview before dispatch.
 `;
 const CONCEPT_ITERATION = `# concept: iteration
 
@@ -806,7 +806,7 @@ Treat this as actionable, not transient — re-running won't change anything.
 - \`concepts/run-verbs\` — how \`ish study run\` selects the iteration.
 - \`concepts/people\` — how participants are picked for a run.
 - \`reference/billing-limits\` — \`maxIterationsPerStudy\` cap on iteration creation.
-- \`reference/credits\` — per-iteration-run credit cost & preview shape (\`pair_preview.credit_estimate\` for participant-pair, top-level \`credit_estimate\` otherwise).
+- \`reference/credits\` — per-iteration-run credit draw & preview shape (\`pair_preview.credit_estimate\` for participant-pair, top-level \`credit_estimate\` otherwise).
 `;
 const CONCEPT_ASSIGNMENT = `# concept: assignment
 
@@ -987,7 +987,7 @@ ish ask results a-6ec --json | jq '.rounds[0].aggregates'
 
 Asks carry a top-level \`status\`:
 
-- \`draft\` — created but not dispatched yet. No credits charged. Created
+- \`draft\` — created but not dispatched yet. No credits drawn. Created
   by \`ish ask create --no-dispatch\`.
 - \`running\` — dispatched; the round is executing or queued.
 - \`completed\` — round 1 (or the most recent round) finished.
@@ -1000,10 +1000,10 @@ intact — no \`--verbose\` needed to see it.
 ## Stage-then-dispatch (draft asks)
 
 When you want a human to review the people and prompt **before** any
-credits are spent, separate creation from dispatch:
+credits are drawn, separate creation from dispatch:
 
 \`\`\`
-# 1. Stage — materializes participants, no worker enqueue, no bill yet
+# 1. Stage — materializes participants, no worker enqueue, no credits drawn yet
 ish ask create --workspace w-6ec --name "tagline AB" \\
     --prompt "Which sounds better?" \\
     --variant text:"Short and punchy." \\
@@ -1013,18 +1013,20 @@ ish ask create --workspace w-6ec --name "tagline AB" \\
 
 # Returns an ask with status="draft". Hand the alias back to the user.
 
-# 2. Dispatch — flips DRAFT → RUNNING and enqueues the round (BILLABLE)
+# 2. Dispatch — flips DRAFT → RUNNING and enqueues the round (draws credits)
 ish ask dispatch a-6ec --wait
 \`\`\`
 
 \`--no-dispatch\` requires people flags (participants are still materialized
-at create time — only the worker enqueue and billing are deferred). It
-is incompatible with \`--wait\` since there is nothing to wait for.
+at create time — only the worker enqueue and the credit draw are
+deferred). It is incompatible with \`--wait\` since there is nothing to
+wait for.
 
 \`ish ask dispatch\` is idempotent on the server: a non-DRAFT ask returns
 HTTP 409 (\`already dispatched\`) which the CLI maps to a usage error, so
 re-running the command is safe. The user who calls \`dispatch\` is the
-billing principal — keep that in mind for shared workspaces.
+principal whose credits are drawn — keep that in mind for shared
+workspaces.
 
 ## Reading the verdict
 
@@ -1170,7 +1172,7 @@ deleted ask was the active one.
 - \`concepts/round\` — what a round is and how it executes.
 - \`concepts/people\` — how participants are chosen at ask creation.
 - \`concepts/run-verbs\` — \`ish ask run\` vs \`ish study run\`.
-- \`reference/credits\` — ask rounds bill **one credit per successful participant per round**, regardless of how many \`questions\` were included. The backend's asks worker bills \`amount=succeeded\` once per round dispatch; questions and round-summary synthesis don't trigger separate debits. A 3-person panel with 2 follow-up questions costs \`3\` credits when all complete, the same as a no-questions run. Failed participant responses (pre-flight errors, refusals) don't bill.
+- \`reference/credits\` — ask rounds draw **one credit per successful participant per round**, regardless of how many \`questions\` were included. The backend's asks worker draws \`amount=succeeded\` once per round dispatch; questions and round-summary synthesis don't draw separately. A 3-person panel with 2 follow-up questions draws \`3\` credits when all complete, the same as a no-questions run. Failed participant responses (pre-flight errors, refusals) draw nothing.
 `;
 const CONCEPT_ROUND = `# concept: round
 
@@ -1197,7 +1199,7 @@ ish ask results a-6ec --round 1
 
 Appending questions to a completed round preserves prior data — variant
 comments, picks, ratings, and earlier-question answers all stay. Only
-the new question(s) get dispatched to the existing participants. Cost is
+the new question(s) get dispatched to the existing participants. Usage is
 roughly N phase-2 LLM calls instead of 2N (no phase-1 re-run). Errored
 responses are skipped entirely; completed responses flip to PENDING and
 re-finalize after the new question is answered.
@@ -1902,16 +1904,16 @@ load-bearing return value — same exception \`study run\` makes.
 | Source not terminal (RUNNING / QUEUED) | \`Participant is still running — cancel it first or wait for completion.\` | 2 |
 | Source participant not found | \`Participant not found: <id>\` | 4 |
 | \`additional_steps\` out of range | Client-side parser rejects before the network call | 2 |
-| Insufficient credits | Bubbles the server message; retry only after topping up | 5 |
+| Insufficient credits | Bubbles the server message; retry only after the balance is replenished | 5 |
 | Wait timed out (\`--wait\` only) | \`WaitTimeoutError\` envelope with current status under \`progress.rows[0]\` — the run keeps going server-side; resume with \`study wait <new-participant>\` | 5 |
 
-## Cost model
+## Credit model
 
-\`extend\` charges credits for **only \`additional_steps\`**, not for
+\`extend\` draws credits for **only \`additional_steps\`**, not for
 the source's original \`max_interactions\` cap. The formula is the same
 as \`study run\` for interactive runs: \`max(1, round(N / 10))\` per
-participant. So \`--add-steps 10\` costs **1 credit**; \`--add-steps 50\`
-costs **5 credits**. See \`reference/credits\` for the full table.
+participant. So \`--add-steps 10\` draws **1 credit**; \`--add-steps 50\`
+draws **5 credits**. See \`reference/credits\` for the full table.
 
 ## Worked example — push past the step cap
 
@@ -1945,7 +1947,7 @@ ish study extend pt-072 \\
 
 - \`concepts/run-verbs\` — the top-level decision rule (\`study run\` vs
   \`ask run\`); extend is a lifecycle verb downstream of either.
-- \`reference/credits\` — per-modality cost formulas. \`extend\` follows
+- \`reference/credits\` — per-modality credit-draw formulas. \`extend\` follows
   the interactive formula scaled to \`additional_steps\`.
 - \`reference/aliases\` — the \`t-…\` prefix and how aliases resolve.
 - \`reference/json-mode\` — capture-mode (\`--get participant_alias\`) for
@@ -2366,7 +2368,7 @@ The CLI guarantees these contracts so agents can chain safely:
   \`study update <id> --modality text\` before adding iterations.
 - **\`ask add-questions\` is additive by default.** Appending questions
   preserves variant comments / picks / ratings / prior-question
-  answers; only the new question(s) get dispatched. Cost: roughly N
+  answers; only the new question(s) get dispatched. Usage: roughly N
   phase-2 LLM calls instead of 2N. Pass \`--redispatch-all\` for the
   legacy reset behavior when you want fresh first impressions.
 - **\`ask results --json\` includes \`cross_round_summary\` for 2+
@@ -2990,49 +2992,62 @@ of scope: \`workspace\`, \`config\`, \`docs\`, \`init\`, \`login\`,
   including \`--get workspace.alias\` to capture the active workspace
   without piping \`ish status --json\` through \`jq\`.
 `;
-const REFERENCE_CREDITS = `# reference: credits & cost preview
+const REFERENCE_CREDITS = `# reference: credits & usage preview
 
-Every billable run (study, ask, insight) costs **credits**. The CLI
-surfaces a cost upper bound *before* you dispatch so you can budget. The
-backend is the authoritative source — its rejection envelope on
-\`insufficient_credits\` carries the live required/available pair.
+Credits are ish's **usage allowance** — a resource that runs draw, not
+money you pay per call. Each run (study, ask, insight) **draws credits**
+from the account's balance. Drawing credits to run studies and asks is
+the normal, expected way to use ish — an agent should run them without
+hesitation, the same as making any other tool call. The job here is just
+to be *aware* of the balance, not to ration it.
 
-## How costs are shaped
+**Where credits come from:**
+- **Paid plans (Starter / Pro / Enterprise)** get a **monthly credit
+  allowance** that refills each billing cycle.
+- **The free tier** gets a **one-time signup grant** — it is *not*
+  refilled monthly. Once it's drawn down, the user adds more or upgrades.
+
+The CLI surfaces a usage upper bound *before* you dispatch so you can see
+how much a run will draw. The backend is the authoritative source — its
+rejection envelope on \`insufficient_credits\` carries the live
+required/available pair.
+
+## How usage is shaped
 
 The formula has the same shape across modalities — \`max(1, round(N / 10))\`
 per principal — but the inputs differ. **Treat the rates below as the
 current calibration**; they will evolve as we differentiate per-modality
-compute cost. Agents should:
+compute. Agents should:
 
-- For prospective cost preview: read \`credit_estimate\` from \`study run\`'s
+- For prospective usage preview: read \`credit_estimate\` from \`study run\`'s
   JSON envelope (top-level for solo/media runs; under \`pair_preview\` for
   participant-pair chat).
-- For hard budget checks: catch the backend's \`insufficient_credits\`
+- For hard balance checks: catch the backend's \`insufficient_credits\`
   rejection (HTTP 402; envelope shape below) and react to
   \`required\` / \`available\`.
 
-| Surface             | Per-principal cost              | Total formula                                    | Example                              |
+| Surface             | Per-principal draw              | Total formula                                    | Example                              |
 |---------------------|---------------------------------|--------------------------------------------------|--------------------------------------|
 | Interactive (URL)   | \`max(1, round(steps/10))\`       | \`participants × per-participant\`                           | 10 participants × 30 steps → 30 credits   |
 | Text/image/video/audio/document | same                | same                                             | 5 participants × 20 steps → 10 credits    |
 | Chat (external chatbot, solo) | \`max(1, round(turns/10))\` | \`participants × per-participant\`                           | 5 participants × 12 turns → 10 credits    |
 | Chat (participant pair)  | \`max(1, round(turns/10))\` × 2   | \`conv × per-side × 2\`                            | 3 conv × 14 turns → 6 credits        |
 | Ask round           | 1 / successful response         | \`successful_participants\`                             | 50 responses → 50 credits            |
-| Study insights      | first free, then **10 flat**    | n/a                                              | 2nd analysis → 10 credits            |
+| Study insights      | first included, then **10 flat**    | n/a                                              | 2nd analysis → 10 credits            |
 
 All numbers are **upper bounds**. Early termination, refusals, or
-backend trimming can reduce actual charge.
+backend trimming can reduce the actual draw.
 
-## Capping interactive/media spend (\`--max-interactions\`)
+## Capping interactive/media usage (\`--max-interactions\`)
 
 \`ish study run\` always sends \`max_interactions\` to the backend for
 interactive and media runs. Precedence: \`--max-interactions <n>\` flag
 > the iteration's stored \`details.max_interactions\` > **CLI default
-of 20**. The default exists to prevent runaway spend when a participant
-gets stuck on a broken or non-responsive surface — without a cap, one
-stuck participant can rack up 100+ steps before the SDK gives up. Pass
-\`--max-interactions\` to override (e.g. \`--max-interactions 50\` for
-deeper exploration, \`--max-interactions 5\` for a cheap smoke test).
+of 20**. The default exists to prevent runaway credit draw when a
+participant gets stuck on a broken or non-responsive surface — without a
+cap, one stuck participant can rack up 100+ steps before the SDK gives
+up. Pass \`--max-interactions\` to override (e.g. \`--max-interactions 50\`
+for deeper exploration, \`--max-interactions 5\` for a quick smoke test).
 The confirmation block shows the resolved value and where it came
 from (flag / iteration / CLI default). The JSON envelope's
 \`credit_estimate.breakdown\` reflects the dispatched value.
@@ -3121,7 +3136,7 @@ HTTP 402. The CLI surfaces it as a structured error envelope:
 \`\`\`
 
 Exit code \`1\` (non-retryable). Don't poll — the user has to upgrade or
-free credits before re-dispatch.
+free up credits before re-dispatch.
 
 ## Agent recipe
 
@@ -3135,7 +3150,7 @@ free credits before re-dispatch.
 
 ## Caveats
 
-- The CLI's preview uses the **same formula** the backend bills with,
+- The CLI's preview uses the **same formula** the backend draws against,
   but does **not** make a network preflight call — it's pure math
   client-side. If the backend formula changes mid-version, the preview
   will drift until the CLI is updated. The \`insufficient_credits\`
@@ -3238,9 +3253,9 @@ upgrade or delete an existing resource to free up headroom.
 
 ## Related
 
-- \`reference/credits\` — per-run credit cost & preview (separate from
+- \`reference/credits\` — per-run credit draw & preview (separate from
   these entity caps; this page is about *how many things you can have*,
-  that page is about *how much each run costs*).
+  that page is about *how many credits each run draws*).
 - \`concepts/workspace\` — \`maxProducts\` is per-account.
 - \`concepts/study\`     — \`maxStudiesPerProduct\` gates study creation.
 - \`concepts/iteration\` — \`maxIterationsPerStudy\` gates iteration creation.
@@ -4442,8 +4457,8 @@ const PAGES = [
     },
     {
         slug: "reference/credits",
-        title: "reference: credits & cost preview",
-        description: "Per-modality credit cost formulas, where the CLI surfaces cost estimates (Scale line, pair_preview.credit_estimate, top-level credit_estimate), tier allotments, insufficient_credits error shape.",
+        title: "reference: credits & usage preview",
+        description: "Credits as a usage allowance (paid plans refill monthly; free tier is a one-time signup grant), per-modality credit draw formulas, where the CLI surfaces usage estimates (Scale line, pair_preview.credit_estimate, top-level credit_estimate), tier allotments, insufficient_credits error shape.",
         body: REFERENCE_CREDITS,
     },
     {

package/dist/lib/local-sim/actions.d.ts

@@ -1,10 +1,13 @@
 /**
  * Action executor — resolves elements and executes Playwright actions.
  *
- * Resolution strategy:
+ * Element resolution strategy (browser only):
  * 1. CDP node resolution (using node_id from tree data)
  * 2. Playwright locator fallback (using element_name + element_type)
- * 3. Coordinate fallback (if returned by backend)
+ *
+ * Native (Android) targets are vision-located by the backend and tapped via
+ * normalized coordinates in AndroidDevice.executeAction — that coordinate path
+ * lives there, not here.
  */
 import type { Page } from "playwright-core";
 import type { LocalStepAction, ActionResult, ContextValue, TreeData } from "./types.js";
@@ -13,6 +16,11 @@ import type { TabManager } from "./tabs.js";
  * Execute a single action on the page.
  */
 export declare function executeAction(page: Page, action: LocalStepAction, treeData: TreeData, contextValues: ContextValue[], tabs?: TabManager): Promise<ActionResult>;
+/**
+ * Resolve the actual text to type from an action, handling var/secret value types.
+ * Exported so the native (Android) executor can resolve values the same way.
+ */
+export declare function resolveTextValue(action: LocalStepAction, contextValues: ContextValue[]): string;
 /**
  * Compare two base64 screenshots to detect visible change.
  */

package/dist/lib/local-sim/actions.js

@@ -1,10 +1,13 @@
 /**
  * Action executor — resolves elements and executes Playwright actions.
  *
- * Resolution strategy:
+ * Element resolution strategy (browser only):
  * 1. CDP node resolution (using node_id from tree data)
  * 2. Playwright locator fallback (using element_name + element_type)
- * 3. Coordinate fallback (if returned by backend)
+ *
+ * Native (Android) targets are vision-located by the backend and tapped via
+ * normalized coordinates in AndroidDevice.executeAction — that coordinate path
+ * lives there, not here.
  */
 import { resolveNodeToBoundingBox } from "./browser.js";
 import { isDebugEnabled } from "./debug.js";
@@ -78,7 +81,7 @@ export async function executeAction(page, action, treeData, contextValues, tabs)
                 coordinates = await executeTextInput(page, action, treeData, contextValues);
                 break;
             case "scroll":
-                await executeScroll(page, action, treeData);
+                await executeScroll(page, action);
                 break;
             case "swipe":
             case "pull_to_refresh":
@@ -87,9 +90,6 @@ export async function executeAction(page, action, treeData, contextValues, tabs)
             case "wait":
                 await page.waitForTimeout(action.duration_ms ?? 1000);
                 break;
-            case "navigate_back":
-                await page.goBack({ timeout: 10_000 }).catch(() => { });
-                break;
             case "long_press":
                 coordinates = await executeLongPress(page, action, treeData);
                 break;
@@ -162,7 +162,7 @@ async function resolveElement(page, action, treeData) {
 /**
  * Resolve to a Playwright Locator (for fill/type operations that need a Locator).
  */
-async function resolveLocator(page, action, treeData) {
+async function resolveLocator(page, action) {
     return findElement(page, action);
 }
 /**
@@ -237,7 +237,7 @@ async function executeTextInput(page, action, treeData, contextValues) {
     // Resolve the actual text to type
     const text = resolveTextValue(action, contextValues);
     // Try to get a Playwright locator for fill operations
-    const locator = await resolveLocator(page, action, treeData);
+    const locator = await resolveLocator(page, action);
     if (locator) {
         if (action.mode === "click_type") {
             await locator.click({ timeout: 5000 });
@@ -273,7 +273,7 @@ async function executeTextInput(page, action, treeData, contextValues) {
         }
     }
 }
-async function executeScroll(page, action, treeData) {
+async function executeScroll(page, action) {
     const viewport = page.viewportSize() ?? { width: 1440, height: 900 };
     const amountMap = {
         small: 0.5, medium: 0.8, large: 1.5, extra_large: 3.0,
@@ -378,8 +378,9 @@ async function executeKeyboardShortcut(page, action) {
 // --- Helpers ---
 /**
  * Resolve the actual text to type from an action, handling var/secret value types.
+ * Exported so the native (Android) executor can resolve values the same way.
  */
-function resolveTextValue(action, contextValues) {
+export function resolveTextValue(action, contextValues) {
     if (action.value_type === "var" || action.value_type === "secret") {
         const cv = contextValues.find(v => v.name === action.value);
         if (cv?.value)
@@ -433,7 +434,11 @@ export function describeAction(action) {
         case "double_tap":
             return `double_tap on '${element}'${modSuffix}`;
         case "drag":
-            return `drag '${element}'`;
+            return action.drag
+                ? `drag '${element}' (${action.drag.startX},${action.drag.startY}→${action.drag.endX},${action.drag.endY})`
+                : `drag '${element}'`;
+        case "rotate_device":
+            return `rotate_device ${action.orientation ?? "?"}`;
         case "think":
             return `think: "${(action.thoughts ?? "").slice(0, 50)}"`;
         case "pull_to_refresh":