tapline-host 1.4.0 → 1.6.0

package/dist/uxcheck.d.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+/** AGENT-TOOLS 1.12 §17.3: `ux_check`, the screen against the basics, and the user's house rules. */
+/** An action seen on a screen: its label, and its testID when it has one. */
+export interface UxAction {
+    label: string;
+    id?: string;
+}
+/** What a journey keeps and hands to `ux_check`. The journey module sets `tools.uxJourney` to one of these. */
+export interface UxJourneyHook {
+    /**
+     * The named actions of the screens seen earlier in the running journey (not this screen's own), or null when
+     * no journey is running: naming is then not checked, and the answer says so.
+     */
+    earlier(): UxAction[] | null;
+    /** Called after each `ux_check`, with the screen's title, its named actions and what was found. */
+    seen?(screen: string, actions: UxAction[], findings: UxFindingSummary[]): void;
+}
+export interface UxFindingSummary {
+    kind: string;
+    problem: string;
+    basis: string;
+    /** The element's ref, when the finding concerns one. */
+    ref?: string;
+    /** The element's frame in points, for the report's red box. */
+    frame?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export declare const uxResultSchema: z.ZodObject<{
+    issues: z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        element: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            ref: z.ZodString;
+            type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            testID: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            textMore: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            value: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
+            placeholder: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            frame: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strip>>>;
+            actions: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+            disabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+            selected: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+            checked: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
+            row: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        }, z.core.$strip>>>;
+        where: z.ZodOptional<z.ZodObject<{
+            frame: z.ZodOptional<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strip>>;
+            text: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        problem: z.ZodString;
+        basis: z.ZodString;
+        at: z.ZodOptional<z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            direct: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    checked: z.ZodArray<z.ZodString>;
+    choices: z.ZodOptional<z.ZodNumber>;
+    actions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type UxResult = z.infer<typeof uxResultSchema>;
+export declare const MAX_UX_FINDINGS = 30;
+export declare const JUDGMENT_LINE = "Add your own judgment from the screenshot, and label it as judgment.";
+/** The report: header, numbered findings (each `at` on its own line), house rules to judge, what was checked, the ask. */
+export declare function formatUxCheck(title: string, result: UxResult, options: {
+    textRules?: readonly string[];
+    journeyRunning: boolean;
+    eyes?: boolean;
+}, pathOf?: (file: string) => string): string;
+export interface UxRules {
+    /** Rules written as text: handed to the agent to judge. */
+    text: string[];
+    /** `{"way_back": true}`: every screen has a visible way back (checked by `ux_check`). */
+    wayBack: boolean;
+    /** `{"max_taps_to_goal": N}`: a journey that reaches its goal in more taps breaks it (checked by the journey at stop). */
+    maxTapsToGoal?: number;
+}
+export declare const NO_UX_RULES: UxRules;
+/** Checks a parsed `--ux-rules` file; throws with a plain message when it isn't one. */
+export declare function parseUxRules(json: unknown, label: string): UxRules;
+/** Reads `--ux-rules FILE`; throws with a plain message when it isn't readable or isn't one. */
+export declare function loadUxRules(path: string): UxRules;

package/dist/uxcheck.js

@@ -0,0 +1,128 @@
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { whereWords } from "./audit.js";
+import { formatElement } from "./format.js";
+import { shownPath } from "./inspect.js";
+import { elementSchema } from "./protocol.js";
+export const uxResultSchema = z.object({
+    issues: z.array(z.object({
+        kind: z.string(),
+        element: elementSchema.nullish(),
+        where: z
+            .object({
+            frame: z.object({ x: z.number(), y: z.number(), width: z.number(), height: z.number() }).optional(),
+            text: z.string().optional(),
+            label: z.string().optional(),
+        })
+            .optional(),
+        problem: z.string(),
+        basis: z.string(),
+        at: z.object({ file: z.string(), line: z.number(), direct: z.boolean().optional() }).optional(),
+    })),
+    checked: z.array(z.string()),
+    choices: z.number().optional(),
+    actions: z.array(z.object({ label: z.string(), id: z.string().optional() })).default([]),
+});
+export const MAX_UX_FINDINGS = 30;
+export const JUDGMENT_LINE = "Add your own judgment from the screenshot, and label it as judgment.";
+const CHECK_WORDS = {
+    choices: "competing choices",
+    main_action: "main action",
+    thumb_reach: "thumb reach",
+    icon_only: "icon-only buttons",
+    cut_off_text: "cut-off text",
+    contrast: "contrast",
+    target_size: "target size",
+    naming: "naming across screens",
+    dead_end: "error and empty states",
+    way_back: "way back (house rule)",
+};
+/** The checks in the order the tail lists them. */
+const CHECK_ORDER = Object.keys(CHECK_WORDS);
+/** The report: header, numbered findings (each `at` on its own line), house rules to judge, what was checked, the ask. */
+export function formatUxCheck(title, result, options, pathOf = shownPath) {
+    const n = result.issues.length;
+    const eyes = options.eyes === true;
+    const lines = [`UX check of ${JSON.stringify(title)}: ${n} finding${n === 1 ? "" : "s"}.`];
+    result.issues.slice(0, MAX_UX_FINDINGS).forEach((issue, i) => {
+        const what = issue.element ? formatElement(issue.element, { actions: false, eyes }) : whereWords(issue.where);
+        lines.push(`${i + 1}. ${issue.kind}: ${what}: ${issue.problem} (${issue.basis})`);
+        // In a user's eyes (AGENT-TOOLS 1.12 §17.1) the code behind the screen isn't shown: no file and line.
+        if (issue.at !== undefined && !eyes) {
+            const library = issue.at.direct === false ? " (a library draws it; this is the app's line around it)" : "";
+            lines.push(`   at ${pathOf(issue.at.file)}:${issue.at.line}${library}`);
+        }
+    });
+    if (n > MAX_UX_FINDINGS)
+        lines.push(`(+${n - MAX_UX_FINDINGS} more findings.)`);
+    const rules = options.textRules ?? [];
+    if (rules.length > 0)
+        lines.push(`House rules to judge: ${rules.map((r) => JSON.stringify(r)).join("; ")}.`);
+    const done = CHECK_ORDER.filter((k) => result.checked.includes(k));
+    const notes = [];
+    if (!result.checked.includes("naming")) {
+        notes.push(`${CHECK_WORDS["naming"]} (${options.journeyRunning ? "no earlier screens yet" : "no journey is running"})`);
+    }
+    lines.push(`Checked: ${done.map((k) => CHECK_WORDS[k]).join(", ")}.${notes.length > 0 ? ` Not checked here: ${notes.join(", ")}.` : ""}`);
+    lines.push(JUDGMENT_LINE);
+    return lines.join("\n");
+}
+export const NO_UX_RULES = { text: [], wayBack: false };
+const KNOWN_KEYS = ["max_taps_to_goal", "way_back"];
+/** Checks a parsed `--ux-rules` file; throws with a plain message when it isn't one. */
+export function parseUxRules(json, label) {
+    const bad = (why) => new Error(`${label} isn't a set of UX rules: ${why}`);
+    if (typeof json !== "object" || json === null || Array.isArray(json))
+        throw bad('expected {"version": 1, "rules": [...]}');
+    const file = json;
+    for (const key of Object.keys(file))
+        if (key !== "version" && key !== "rules")
+            throw bad(`unknown key ${JSON.stringify(key)}`);
+    if (file["version"] !== 1)
+        throw bad("version must be 1");
+    const list = file["rules"];
+    if (!Array.isArray(list))
+        throw bad("rules must be a list");
+    const rules = { text: [], wayBack: false };
+    list.forEach((rule, i) => {
+        const at = `rule ${i + 1}`;
+        if (typeof rule === "string") {
+            if (rule.trim() === "")
+                throw bad(`${at} is empty`);
+            rules.text.push(rule.trim());
+            return;
+        }
+        if (typeof rule !== "object" || rule === null || Array.isArray(rule))
+            throw bad(`${at} must be text or an object`);
+        const keys = Object.keys(rule);
+        const key = keys[0];
+        if (keys.length !== 1 || key === undefined)
+            throw bad(`${at} must have exactly one key`);
+        if (!KNOWN_KEYS.includes(key))
+            throw bad(`unknown key ${JSON.stringify(key)} in ${at} (known: ${KNOWN_KEYS.join(", ")})`);
+        const value = rule[key];
+        if (key === "way_back") {
+            if (typeof value !== "boolean")
+                throw bad(`way_back in ${at} must be true or false`);
+            rules.wayBack = value;
+        }
+        else {
+            if (typeof value !== "number" || !Number.isInteger(value) || value < 1)
+                throw bad(`max_taps_to_goal in ${at} must be a whole number of 1 or more`);
+            rules.maxTapsToGoal = value;
+        }
+    });
+    return rules;
+}
+/** Reads `--ux-rules FILE`; throws with a plain message when it isn't readable or isn't one. */
+export function loadUxRules(path) {
+    let json;
+    try {
+        json = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`couldn't read the UX rules ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return parseUxRules(json, path);
+}
+//# sourceMappingURL=uxcheck.js.map

package/dist/uxcheck.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tapline-host",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Tapline host: lets AI agents see and drive your own React Native / Expo app on a test phone on the same Wi-Fi (MCP server and CLI).",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,7 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "tapline": "dist/cli.js"
+    "tapline": "dist/bin.js"
   },
   "files": [
     "dist",
@@ -44,6 +44,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",
+    "gifenc": "1.0.3",
     "jpeg-js": "^0.4.4",
     "qrcode": "^1.5.4",
     "ws": "^8.22.1",

package/skills/tapline/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: tapline
-description: Use when testing, exploring or driving the user's own React Native or Expo app on their real phone through Tapline (MCP tools such as look, tap, type_text, run, audit, inspect, wait_for, open_url, app_command, logs, crash, performance, session_report), when asked for QA, an accessibility check, a UI check or a bug hunt on that app, when asked where in the code a screen element comes from, when setting Tapline up for a user or adding its SDK to an app, or when a Tapline call answers not_connected, in_background, not_actionable, not_allowed, not_answering or reconnecting.
+description: Use when testing, exploring or driving the user's own React Native or Expo app on their real phone through Tapline (MCP tools such as look, tap, type_text, run, drive, map, audit, inspect, wait_for, open_url, app_command, logs, crash, performance, session_report), when asked for QA, an accessibility check, a UI check or a bug hunt on that app, when asked where in the code a screen element comes from, when setting Tapline up for a user or adding its SDK to an app, or when a Tapline call answers not_connected, in_background, not_actionable, not_allowed, not_answering or reconnecting.
 license: MIT
 compatibility: Needs the Tapline MCP server (`tapline mcp`, Node.js 20 or later) on the user's computer, and a development or TestFlight build of the app with Tapline's SDK switched on. Works from Windows, macOS or Linux.
 metadata:
   tool: tapline
-  interface: AGENT-TOOLS v1.8
+  interface: AGENT-TOOLS v1.13
 ---
 
 # Tapline: test your own app on a real phone
@@ -97,6 +97,39 @@ run {"steps": [
   through the phone's Settings.
 - After a long session, `session_report` shows where the calls went and which ones were wasted.
 
+**Known ground: `drive`.** Tapline learns the app as you work: its places (screens by route
+pattern), the roads between them, links and routes. The header's `Place:` line says where you are. Once
+the map knows a place, go there in one call and read the answer, which has the screen:
+
+```
+drive {"to": "language"}
+
+Arrived at language by 3 taps in 1.9 s.
+```
+
+- On known ground, `drive` yourself in one call; don't tap step by step. On unknown ground, hand the
+  goal to one small, fast agent and keep one driver. Never two drivers on one phone.
+- `map` lists what is known (places, roads, routes, reflexes) and touches nothing; `map {"to": "x"}`
+  shows the way. `drive` takes `by` (`taps`, `link`), `with` (a link's params, a route's variables),
+  `then` (`run` steps) and `dry_run`. It works as a `run` step too.
+- `off_route` means a road didn't hold. Nothing more was touched: read the screen in the answer and
+  go on by hand. Don't repeat the drive.
+- A route is a saved flow: `record` with `route`, then `drive {"route": "sign_in", "with": {...}}`.
+- A reflex, `map {"reflex": {...}}`, closes a known interruption by itself (a rate prompt) and says
+  `Reflex: closed ...`. Only declared ones run. Add one only for something you have seen.
+- Tapline never navigates from inside the app: a drive is the app's own taps or a deep link.
+- `run` steps take `if` and `optional` for what may or may not show up; a skipped step is said.
+  `brief: true` shortens an action's answer to 12 element lines; `look` is never brief.
+
+**Accounts by name.** When the user started Tapline with `--accounts`, `type_text` takes `account:
+"tester2"` and the whole text `${account.username}` or `${account.password}`; `run` and `drive` take
+`account` too. You never see the value, and you never put a password in a call, a note or a commit.
+Use only accounts from that file.
+
+**Speed.** `tapline call <tool> '<json>'` is one call to a running `tapline host`, for when no MCP
+server is loaded; loading one per call costs about 2 s. `app_command animations {"speed": "fast"}`
+makes transitions nearly instant; turn it off (`normal`) before a visual check. It is opt-in.
+
 Name the element with one of, in this order of preference: `id` (the app's own identifier,
 React Native's `testID`), `ref` (from your last list, like `e3`), `label`, `text`. Use `x`
 and `y` only for things with no element.
@@ -109,15 +142,17 @@ and `y` only for things with no element.
   (`[tap, longPress]`).
 - **`Same screen. Changes:`** then `+` new, `-` gone, `~` changed (with what it was),
   `↕` moved. When most of the screen changed, the full list comes instead.
-- **`No visible change.`** means nothing changed, on screen or off it.
+- **`No visible change.`** means nothing changed, on screen or off it. After a tap it is followed by
+  `Note: the tap was delivered, and nothing on screen changed within 0.5 s.` and, when known, why (the
+  handler threw, only a parent's took it, a request is still running). Read it: the tap may be a bug.
 - **A sheet, an alert or a new screen answers with the full list:** the first line, then
   `Screen …` and the elements that are in front now. What a sheet hides is left out until it
   closes; acting on it answers `covered: … close that first.` When something out of view
   changed as well, it follows the list under `Changes off screen:`.
 - **The header counts what you can't see:**
   `Screen 430x932 pt @3x · 26 elements (+41 below, +2 above)`. Those 41 are reached by
-  scrolling. They are not in the list: acting on one answers `off_screen` and names the call
-  that brings it up. `Route:` names the screen you are on, and `Network:` says requests are still
+  scrolling. They are not in the list, but `tap`, `long_press`, `toggle` and `type_text` scroll to one
+  themselves. `off_screen` means no scroll can bring it on screen: look at the screen, then target something else or report it. `Route:` names the screen you are on, and `Network:` says requests are still
   running.
 - **A change out of view has its own line, without a ref:**
   ```
@@ -148,7 +183,7 @@ and `y` only for things with no element.
 
 | To | Call |
 |---|---|
-| reach an element that is off screen | `scroll` with it as `target` and `to: "target"`. One call; don't scroll by guess |
+| reach an element that is off screen | `tap`, `long_press`, `toggle` and `type_text` scroll to it themselves. To only bring it into view: `scroll` with it as `target` and `to: "target"`. Don't scroll by guess |
 | wait for a load, a spinner or a new screen | `wait_for` with `text`, `id` or `label` (`gone: true` for a spinner; `network_idle` for requests), not `wait` |
 | set a switch, or read it | `toggle` with `value: true` or `false`. It does nothing if the switch is already there, and its answer says the switch's state either way |
 | fill a field and send it | `type_text` with `submit: true` |
@@ -184,7 +219,7 @@ Every failure is `Error <code>: <message>`, and the message says what to do next
 |---|---|
 | `not_found` | `look`, then pick another target |
 | `ambiguous` | use one of the listed refs, or add `index` |
-| `not_actionable` | the first word is why: `disabled`, `off_screen`, `covered`, `under_tab_bar`, `behind_alert`, `no_action`. Fix the cause: `scroll` with `to: "target"`, close what is in front, answer the alert |
+| `not_actionable` | the first word is why: `disabled`, `off_screen`, `covered`, `under_tab_bar`, `behind_alert`, `no_action`. Fix the cause: close what is in front, answer the alert; for `off_screen`, target something else or report it (nothing scrolls there) |
 | `stale` | a person changed the screen since your list: `look` again |
 | `busy` | a person is using the app: wait a few seconds, retry |
 | `paused`, `in_background` | ask the user (to resume; to open the app again) |
@@ -194,7 +229,9 @@ Every failure is `Error <code>: <message>`, and the message says what to do next
 | `timeout` | the action may have happened: `look` before you retry |
 | `unsupported` | Tapline can't do this: use what the message names |
 | `bad_params` | fix the call |
-| `not_allowed` | the first word is why. `needs_confirmation`: a person must allow this touch in the live view; tell the user, and when they have, make the same call again. `blocked`: the safety policy forbids it; don't try another way |
+| `not_allowed` | the first word is why. `needs_confirmation`: a person must allow this touch. Usually the host asks in a dialog and in the live view and your call waits (up to 120 s) for the answer; `They declined.` means ask your user, don't repeat the call. With no dialog: tell the user, and when they have allowed it in the live view, make the same call again. `blocked`: the safety policy forbids it; don't try another way |
+| `off_route` | a `drive` road didn't hold; nothing more was touched. Read the screen and go on by hand |
+| `Needs a person: ...` | the host's dialog (or a `Note:`) names what a person must do on the phone (open the app, tap an alert). The call goes on by itself when it clears; `They can't now.` means ask your user |
 | `expect_failed` | a `run` step's `expect` didn't hold: `look`, then fix the step or report the bug |
 | `internal` | a bug in the tool: report it with the call you made |
 
@@ -239,18 +276,27 @@ Evidence: screenshot moment, if any.
 Then, apart from the bugs: what passed, what you couldn't test and why, and screens that
 took more than a few seconds (`Settled in` gives the time).
 
+**As a real user.** When the question is whether people can find, understand and finish a feature, not only
+whether it works, run a `journey`: `start` with a `goal` and a `persona`, act as that person would (you see
+only what is on the glass, and target by ref or visible text), then `stop` with `reached`. The tool measures
+the taps, the time, the wrong turns and the hesitations, and writes a visual report. Build personas for this
+app's own users and agree them with your user: [references/personas.md](references/personas.md) has the
+recipe and examples. `ux_check` checks a screen against usability basics along the way.
+
 ## 7. Safety
 
 - It is the user's own phone and their real app data. Don't buy, subscribe, send messages or
   email, post, delete data, or change account, privacy or security settings, unless the user
   asked for exactly that step. Ask when unsure.
-- Use the test accounts and test data the user gives you. Never sign in with credentials
-  you find in the app or its logs.
+- Test accounts come only from the user's accounts file (`--accounts`), used by name. Use the
+  test data the user gives you. Never sign in with credentials you find in the app or its logs, and
+  never print, repeat or commit one.
 - Don't read or repeat private content you see (messages, photos, notifications) beyond
   what the test needs.
 - Stay in the app under test.
 - Some touches need a person's OK first: a button whose label says Buy, Pay, Delete, Send,
-  Post, Sign out and the like answers `needs_confirmation`, and the live view asks the person.
+  Post, Sign out and the like needs a person: the host's dialog and the live view ask them, and
+  a `drive` or `run` stops there like a single touch. A reflex never takes such a touch.
   You can never give that OK yourself, and you never look for another way to the same result
   (another button, a deep link, `x` and `y`). `dry_run: true` tells you beforehand.
 - Give the live view's link to the user only. It carries a key. A pairing link lets a phone

package/skills/tapline/references/personas.md

@@ -0,0 +1,45 @@
+# Personas for usability journeys
+
+A persona is a short description of one kind of user, so a journey is judged by the right eyes. No tool enforces it:
+you build it, agree it with your user, and keep to it while you test. A persona's conditions are values of
+`language`, `region`, `text_size` and `network`; pass these as `conditions` on `journey { start }`; each tool applies
+them its own way.
+
+## Build one for the app at hand
+
+Ask the user who really uses this app, then write five lines per persona:
+
+1. **Who:** age, job, how often they use the app, what device they have.
+2. **Knows:** what they already know about the app and about apps like it.
+3. **Wants:** the one goal of this journey, in their words ("log my breakfast").
+4. **Situation:** where they are and what else is going on (on a bus, one hand free, in a hurry).
+5. **Conditions:** the `language`, `region`, `text_size` and `network` that fit, if any.
+
+Two or three personas that differ a lot beat six that are alike. Name the persona in `journey { start }`, and read each
+screen as they would: what they would notice first, what they would tap, where they would hesitate.
+
+## Examples to copy, extend or ignore
+
+**First-timer.** Has never seen the app; knows only what the store page told them. Wants to finish the first task
+without reading help. Reads every label, hesitates at jargon and at icons without words, never scrolls to find a
+hidden option. Conditions: none, a fresh install.
+
+**Busy regular.** Uses the app daily, knows where things are, wants it done in as few taps as possible, one hand, while
+walking. Notices every extra step and every changed button name. Conditions: `network: 3g`.
+
+**Older user with large text.** Reads slowly, avoids small targets, does not guess what an unlabelled icon does. Wants
+the same task with text at the largest size, so cut-off text and overlapping controls show up.
+Conditions: `text_size: ax3`.
+
+**Right-to-left speaker.** Reads Arabic; expects the layout mirrored, back arrows pointing the other way, numbers and
+mixed text in order. Wants a task done in their own language. Conditions: `language: ar · region: QA`.
+
+**Poor connection.** On a train or abroad, the network drops and crawls. Wants to know what happened when something
+does not load, and to retry without losing what they typed. Conditions: `network: 3g`, and a `network` stress step to
+`offline` at the worst moment (a field half filled, a form being sent).
+
+**One-handed on a big phone.** Holds a large phone in one hand and can only reach the lower half with a thumb. Wants
+to finish the task without stretching or using the other hand. Conditions: none, a large phone.
+
+Each line above is a starting point: change the details to match the app's real users. Write the conditions on one line
+the way the examples do, for example `language: ar · region: QA · text_size: xl · network: 3g`.

package/skills/tapline/references/setup.md

@@ -110,6 +110,11 @@ tapline mcp
 - `--policy FILE` sets the words that need a person's OK or are blocked (JSON, per app);
   `--no-policy` turns the policy off, only for a test phone with test data. `--no-log` turns
   off the action log in `~/.tapline/log/`.
+- `--no-dialog` keeps a person's OK to the live view (the host's own dialog is off), for a host that
+  hands dialogs to the model instead of a person. `--brief` makes actions answer briefly.
+  `--accounts FILE` loads test accounts (outside any git repository, or ignored by it; never print
+  it). `--maps DIR` keeps each app's map in `DIR/<app id>/`. `tapline host` takes the same options
+  and serves `tapline call`.
 
 **Claude Code**
 
@@ -155,7 +160,7 @@ Run `tapline doctor` first.
 | the phone can't connect, on Windows | the firewall: `tapline doctor` names the rule for ports 7210 to 7219 (it allows the local subnet and Tailscale) |
 | the phone can't connect, on any computer | the phone and the computer are on different networks, or the Wi-Fi blocks devices from each other (guest networks do) |
 | the app doesn't ask to connect after `pair` with no scheme | the offer lasts 10 minutes: call `pair` again. `metro.config.js` needs `withTapline`; same Wi-Fi; the code must load from this computer's Metro, not a tunnel. TestFlight and release builds need the QR code |
-| `not_allowed: needs_confirmation` | a policy word (Buy, Delete, Send …) is on the element: the user allows it in the live view (`viewer`), then repeat the call within 120 s. Use `--no-policy` only on a test phone, with the user's OK |
+| `not_allowed: needs_confirmation` | a policy word (Buy, Delete, Send …) is on the element: the user allows it in the host's dialog or the live view (`viewer`); with no dialog, repeat the call within 120 s after they have. Use `--no-policy` only on a test phone, with the user's OK |
 | the list is empty, "No React roots recorded" | the `register` import isn't the first line of the entry file |
 | a pairing link opens a "not found" screen | Expo Router: `app/+native-intent.ts` is missing |
 | every call answers `in_background` | the app isn't in front: the user opens it again |