@aarwitz/tapp 0.17.3 → 0.17.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tapp",
   "description": "Give Claude hands and eyes on iOS, Android, and web apps, with exploration, replayable flows, evidence, and deterministic CI gates.",
-  "version": "0.17.3",
+  "version": "0.17.5",
   "author": {
     "name": "Aaron Horowitz",
     "url": "https://github.com/aarwitz"
@@ -24,7 +24,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@aarwitz/tapp@0.17.3",
+        "@aarwitz/tapp@0.17.5",
         "mcp"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}"

package/AGENTS.md

@@ -106,7 +106,13 @@ Rules that prevent 90% of failures:
    secret-templated replay step and avoids native secure-field refocus behavior.
 5. Tap results: `ok` (landed), `not_hittable` (exists but disabled/covered — the harness
    auto-dismisses keyboards and retries), `not_found` (nothing matches — re-read the tree).
-6. One session at a time. `session_start` always begins from a fresh app launch.
+6. One session at a time. `session_start` always begins from a fresh **cold** launch
+   (terminate + relaunch, for a deterministic starting screen). Persisted app data such as
+   Keychain credentials survives, but the app opens on its launch screen, not a resumed
+   foreground state — an app that gates each cold start behind sign-in WILL show its login
+   wall, so plan `login` (or a bypass launch argument) as the first act. Plain `tapp tree` /
+   `tapp screenshot` warm-resume the currently foregrounded app instead, which is why they can
+   look signed-in when a fresh session does not.
 
 ## Autonomous exploration (`tapp_explore`)
 
@@ -145,6 +151,11 @@ without a coding agent, model, subscription, or API key. AI generation and `asse
   a final screen assertion auto-inserted; typed credentials are templated to `$TEST_EMAIL`/`$TEST_PASSWORD`.
 - **Replay:** `tapp_flow_run { flowPath: ".tapp/flows/checkout.yml" }` — exact steps,
   deterministic assertions, same result every time. A failed assertion is a finding.
+- **Credentials at replay:** pass real values (`testEmail`/`testPassword`, CLI `--email`/
+  `--password`), or name a configured actor (`actor: "coach"`, CLI `--actor coach`) and Tapp
+  resolves `$TEST_EMAIL`/`$TEST_PASSWORD` from the env vars that actor binds. Actors store
+  env-var **names** only — never values. `tapp actor set` refuses to overwrite an existing
+  actor unless you pass `--replace`, so idempotent setup scripts must include it.
 - **Generate:** `tapp_flow_generate { goal: "log in and add the first item to cart" }` —
   grounded in the app's actually-explored screens, so it can't invent steps.
 - **Discover the file format without MCP:** `npx -y @aarwitz/tapp@latest flow example` prints a
@@ -161,6 +172,15 @@ without a coding agent, model, subscription, or API key. AI generation and `asse
   and installs from an Xcode project/workspace; or the user's normal build).
 - A simulator must be booted (`tapp_list_simulators` → `tapp_boot_simulator`).
 - Screenshots/captures land in `~/.tapp/captures/`.
+- Driving `tapp mcp` from a raw stdio client: **consume or discard stderr** — the server logs
+  progress there, and an unread stderr pipe can deadlock a naive client. The first
+  `tapp_session_start` on a cold machine includes the one-time harness build, so it can take
+  minutes before the first result arrives; that is startup cost, not a hang.
+- Managed web targets always bind `127.0.0.1` and prefer the repository's declared or framework
+  default port (vite → 5173, next → 3000). If the app's backend uses a CORS allowlist, pin the
+  origin with `"web": { "port": 5173 }` in `.tapp/project.json` — an unexpected port surfaces as
+  misleading fetch/CORS findings, and a busy pinned port is a hard error, never a silent
+  ephemeral fallback.
 
 ## Honesty rules
 

package/README.md

@@ -348,7 +348,7 @@ jobs:
     timeout-minutes: 45
     steps:
       - uses: actions/checkout@v4
-      - uses: aarwitz/tapp@v0.17.3 # or pin the reviewed release commit SHA
+      - uses: aarwitz/tapp@v0.17.5 # or pin the reviewed release commit SHA
         with:
           project: MyApp.xcodeproj # or MyApp.xcworkspace
           scheme: MyApp
@@ -398,7 +398,7 @@ Android CI runs on Linux with an emulator/device already connected. The Action c
 or accept a prebuilt one:
 
 ```yaml
-- uses: aarwitz/tapp@v0.17.3 # or pin the reviewed release commit SHA
+- uses: aarwitz/tapp@v0.17.5 # or pin the reviewed release commit SHA
   with:
     platform: android
     android-app-id: com.acme.app

package/bin/tapp.js

@@ -262,15 +262,15 @@ async function resolveTargetOrExit(engine, input) {
 
 function safeCommandUsage(verb) {
   const usage = {
-    explore: "tapp explore [target] [--platform ios|android|web] [--actions N] [--timeout SEC] [--email VALUE] [--password VALUE] [--baseline FILE] [--json FILE]\n  Web: [--watch] opens Tapp's controlled browser and shows its actions\n  iOS launch configuration: [--launch-arg VALUE ...] [--launch-env '{\"KEY\":\"VALUE\"}']\n  Android: [--app-id ID] [--apk FILE] [--serial ID] [--keep-data]",
+    explore: "tapp explore [target] [--platform ios|android|web] [--actions N] [--timeout SEC] [--email VALUE] [--password VALUE] [--baseline FILE] [--json FILE]\n  Web: [--watch] opens Tapp's controlled browser and shows its actions; [--device \"iPhone 13\"] [--viewport 390x844] render at a device profile or explicit size\n  iOS launch configuration: [--launch-arg VALUE ...] [--launch-env '{\"KEY\":\"VALUE\"}']\n  Android: [--app-id ID] [--apk FILE] [--serial ID] [--keep-data]",
     focus: "tapp focus \"SCREEN OR CONTROL\" [target] [--platform ios|android|web] [--project-dir REPO] [--target NAME|PATH] [--map FILE] [--out FILE]",
     init: "tapp init [repo] [--explore] [--refresh] [--platform PLATFORM] [--target NAME] [--url URL] [--watch] [--dry-run]",
-    open: "tapp open [target] [--platform ios|android|web] [--out FILE] [--tap TEXT] [--wait-for TEXT]",
-    tree: "tapp tree [target] [--platform ios|android|web] [--json] [--tap TEXT] [--wait-for TEXT]",
+    open: "tapp open [target] [--platform ios|android|web] [--out FILE] [--tap TEXT] [--wait-for TEXT]\n  Web: [--device \"iPhone 13\"] [--viewport 390x844] [--full-page]",
+    tree: "tapp tree [target] [--platform ios|android|web] [--json] [--tap TEXT] [--wait-for TEXT]\n  Web: [--device \"iPhone 13\"] [--viewport 390x844]",
     shot: "tapp shot [--out FILE]",
     apps: "tapp apps",
     build: "tapp build [repo] [--scheme NAME] [--configuration NAME]",
-    flow: "tapp flow example\ntapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--email VALUE] [--password VALUE]",
+    flow: "tapp flow example\ntapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--actor NAME] [--email VALUE] [--password VALUE] [--device \"iPhone 13\"] [--viewport 390x844]",
     task: "tapp task validate FILE [--platform PLATFORM] [--map FILE]\ntapp task compile FILE --platform PLATFORM [--inputs JSON] [--out FILE]\ntapp task run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID] [--inputs JSON]",
     contract: "tapp contract validate FILE [--platform PLATFORM] [--map FILE]\ntapp contract compile FILE --platform PLATFORM [--out FILE]\ntapp contract run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID]",
     scenario: "tapp scenario validate FILE [--project-dir DIR]\ntapp scenario run FILE --platform web --url URL [--project-dir DIR]",
@@ -279,7 +279,7 @@ function safeCommandUsage(verb) {
     plan: "tapp plan show [FILE]\ntapp plan review [FILE] --approve NAME[,NAME] --reject NAME[,NAME] --defer NAME[,NAME]\ntapp plan generate|validate|promote [FILE] [options]",
     baseline: "tapp baseline create [repo] [--platform PLATFORM] [--target NAME] [--from GATE.json] [--replace]",
     ci: "tapp ci ...\ntapp ci install [repo] [--out FILE] [--manifest FILE] [--dry-run] [--replace]",
-    actor: "tapp actor set NAME --email-env ENV --password-env ENV [--project-dir DIR]\ntapp actor list [repo]",
+    actor: "tapp actor set NAME --email-env ENV --password-env ENV [--replace] [--project-dir DIR]\ntapp actor list [repo]",
     app: "tapp app [repo] [--no-open] [--port PORT]",
     report: "tapp report [captureId|latest]",
     doctor: "tapp doctor",
@@ -774,6 +774,8 @@ switch (command) {
           testPassword: flags.password,
           baselineFindings,
           watch: flags.watch === true,
+          device: typeof flags.device === "string" ? flags.device : "",
+          viewport: typeof flags.viewport === "string" ? flags.viewport : "",
           surface: "cli",
           onProgress,
         })
@@ -827,6 +829,9 @@ switch (command) {
           timeoutMs: Number(flags.timeout) * 1000 || 15_000,
           tapText: typeof flags.tap === "string" ? flags.tap : "",
           waitForText: typeof flags["wait-for"] === "string" ? flags["wait-for"] : "",
+          device: typeof flags.device === "string" ? flags.device : "",
+          viewport: typeof flags.viewport === "string" ? flags.viewport : "",
+          fullPage: flags["full-page"] === true,
         });
         const out = typeof flags.out === "string" ? path.resolve(flags.out) : path.join(tappHome, "shots", `web-${Date.now()}.png`);
         fs.mkdirSync(path.dirname(out), { recursive: true });
@@ -899,6 +904,8 @@ switch (command) {
           screenshot: false,
           tapText: typeof flags.tap === "string" ? flags.tap : "",
           waitForText: typeof flags["wait-for"] === "string" ? flags["wait-for"] : "",
+          device: typeof flags.device === "string" ? flags.device : "",
+          viewport: typeof flags.viewport === "string" ? flags.viewport : "",
         });
         if (flags.json) console.log(JSON.stringify({ platform: "web", url: snap.url, screenTitle: snap.screenTitle, settled: snap.settled, elements: snap.elements }, null, 2));
         else console.log(engine.formatScreen(snap.screenTitle, snap.elements));
@@ -1111,7 +1118,7 @@ switch (command) {
       break;
     }
     if (!["run", "validate"].includes(verb) || !flowPath) {
-      console.error("usage: tapp flow example\n       tapp flow run <flow.yml> [--platform ios|android|web] [--url URL] [--app-id ID] [--apk FILE] [--serial ID]\n       tapp flow validate <flow.yml>");
+      console.error("usage: tapp flow example\n       tapp flow run <flow.yml> [--platform ios|android|web] [--actor NAME] [--email VALUE] [--password VALUE] [--url URL] [--app-id ID] [--apk FILE] [--serial ID]\n       tapp flow validate <flow.yml>");
       process.exit(2);
     }
     const absolute = path.resolve(flowPath);
@@ -1146,6 +1153,30 @@ switch (command) {
     const env = { ...process.env, FLOW_LOG: flowLog, TAPP_FLOW_EVIDENCE_DIR: evidenceDir };
     if (typeof flags.email === "string") env.OCQA_TEST_EMAIL = flags.email;
     if (typeof flags.password === "string") env.OCQA_TEST_PASSWORD = flags.password;
+    if (typeof flags.device === "string") env.TAPP_WEB_DEVICE = flags.device;
+    if (typeof flags.viewport === "string") env.TAPP_WEB_VIEWPORT = flags.viewport;
+    if (typeof flags.actor === "string" && flags.actor) {
+      const { readProjectConfig } = await import(path.join(packageRoot, "mcp-server", "src", "project-config.js"));
+      const loaded = readProjectConfig(process.cwd());
+      if (loaded.errors.length) { console.error(`❌ Invalid ${loaded.relativePath}: ${loaded.errors.join("; ")}`); process.exit(2); }
+      const actor = loaded.config.actors?.[flags.actor];
+      if (!actor) {
+        console.error(`❌ Actor '${flags.actor}' is not configured in ${loaded.relativePath}. Run from the repository root, or configure it: tapp actor set ${flags.actor} --email-env ENV --password-env ENV`);
+        process.exit(2);
+      }
+      // Actors store env-var NAMES only; resolve the values here. Explicit --email/--password win.
+      for (const [credential, flagName, envKey] of [["email", "email", "OCQA_TEST_EMAIL"], ["password", "password", "OCQA_TEST_PASSWORD"]]) {
+        if (typeof flags[flagName] === "string") continue;
+        const binding = actor.credentials?.[credential];
+        if (!binding) continue;
+        const value = process.env[binding.env];
+        if (!value) {
+          console.error(`❌ Actor '${flags.actor}' binds ${credential} to $${binding.env}, but that environment variable is not set.`);
+          process.exit(2);
+        }
+        env[envKey] = value;
+      }
+    }
     let invocation;
     if (platform === "web") {
       const url = typeof flags.url === "string" ? flags.url : flow.url || flow.app;

package/docs/application-model.md

@@ -95,7 +95,11 @@ derived lockfile-backed install command, runs its declared build script when pre
 `start`, `dev`, `serve`, or `preview` package script with argument-array process execution (never
 generated shell source). A static site with no script uses Tapp's local read-only static server. The
 runtime binds to an available loopback port, writes its log under the Tapp runtime directory, and is
-terminated after exploration even when QA fails. Multiple web targets, an unlocked dependency
+terminated after exploration even when QA fails. Port precedence is: an explicit
+`"web": { "port": N }` pin in `.tapp/project.json`, then a port declared by the start script, then
+the framework default (vite 5173, next 3000), then an ephemeral port. Pin the port when a backend
+CORS allowlist expects a fixed origin; a busy or contradicted pin is a hard startup error rather
+than a silent fallback that would resurface as fetch/CORS findings. The host is always `127.0.0.1`. Multiple web targets, an unlocked dependency
 graph, an unrecognized start path, or backend-specific configuration produce explicit remediation;
 provide `--target` and/or an already-running owned `--url` in those cases. Running repository build
 scripts executes repository code and should only be used for a checkout the customer trusts.

package/docs/scenarios.md

@@ -74,7 +74,7 @@ tapp ci --platform web --url http://127.0.0.1:4180 \
 GitHub Action:
 
 ```yaml
-- uses: aarwitz/tapp@v0.17.3 # or pin the reviewed release commit SHA
+- uses: aarwitz/tapp@v0.17.5 # or pin the reviewed release commit SHA
   with:
     platform: web
     url: http://127.0.0.1:4180

package/mcp-server/src/application-model.js

@@ -91,8 +91,15 @@ function applyRuntimeTargetValidation(root, targets, validation) {
   if (!container || !scheme || !bundleId) return targets;
   const captureId = String(validation.evidence?.captureId || "").trim();
   const explored = !!captureId;
+  // The build records the container findXcodeContainer resolved (shallowest workspace-first),
+  // which can differ from the modeled sourcePath in a repo exposing both a workspace and a
+  // project. With exactly one iOS target there is no ambiguity — apply the validation rather
+  // than silently dropping it and re-blocking on scheme confirmation after every refresh.
+  const iosTargets = targets.filter((target) => target.platform === "ios");
+  const pathMatched = iosTargets.some((target) => posix(target.sourcePath) === container);
   return targets.map((target) => {
-    if (target.platform !== "ios" || posix(target.sourcePath) !== container) return target;
+    if (target.platform !== "ios") return target;
+    if (posix(target.sourcePath) !== container && (pathMatched || iosTargets.length !== 1)) return target;
     return {
       ...target,
       status: "configured",
@@ -917,12 +924,25 @@ function mergePlanDecisions(next, prior, { invalidateValidation = false } = {})
     priorByNameScope.set(key, list);
   }
   const consumedPriorIds = new Set();
+  const derivedScopes = new Set(next.items.map((item) => item.scope || "."));
   const carried = next.items.map((item) => {
     const exact = priorItems.get(item.id);
     const lineage = item.origin === "committed"
       ? (priorByNameScope.get(`${item.scope || "."}|${item.name}`) || []).find((candidate) => candidate.origin === "promoted-validated" || candidate.generation?.status === "promoted")
       : null;
-    const previous = exact || lineage;
+    // Proposal ids hash the node's targetId, which can drift between refreshes when target
+    // detection or map attribution shifts. Without name+scope regrounding, that drift strands
+    // the reviewed item as stale AND re-adds the same proposal as pending — a duplicate the
+    // customer already decided.
+    const sameNameScope = exact || lineage ? [] : (priorByNameScope.get(`${item.scope || "."}|${item.name}`) || []).filter((candidate) => !consumedPriorIds.has(candidate.id));
+    const regrounded = sameNameScope.find((candidate) => candidate.decision && candidate.decision !== "pending") || sameNameScope[0] || null;
+    // When a scope stops being derived entirely (its target no longer grounds any proposals — the
+    // mis-attribution case), a decided same-name item from that vanished scope carries the
+    // customer's decision onto the surviving surface instead of lingering as a stale duplicate
+    // beside a re-added pending twin. The migration is recorded via regroundedFromScope.
+    const crossScope = exact || lineage || regrounded ? null
+      : (prior.items || []).find((candidate) => !consumedPriorIds.has(candidate.id) && candidate.name === item.name && !derivedScopes.has(candidate.scope || ".") && candidate.decision && candidate.decision !== "pending") || null;
+    const previous = exact || lineage || regrounded || crossScope;
     if (!previous) return item;
     consumedPriorIds.add(previous.id);
     if (exact && lineage && exact.id !== lineage.id) consumedPriorIds.add(lineage.id);
@@ -936,10 +956,20 @@ function mergePlanDecisions(next, prior, { invalidateValidation = false } = {})
     // A reviewed proposal becomes a committed contract without becoming a different
     // customer decision. Preserve its original plan identity so browser links, CLI
     // item selectors, and review history remain stable across promotion refreshes.
-    return { ...item, id: previous.id, ...human };
+    return { ...item, id: previous.id, ...human, ...(crossScope ? { regroundedFromScope: previous.scope || "." } : {}) };
   });
   const currentIds = new Set(carried.map((item) => item.id));
-  for (const previous of prior.items || []) if (!currentIds.has(previous.id) && !consumedPriorIds.has(previous.id) && previous.decision && previous.decision !== "pending") carried.push({ ...previous, stale: true, status: "not-derived-on-refresh" });
+  const survivorNames = new Set(carried.map((item) => item.name));
+  for (const previous of prior.items || []) {
+    if (currentIds.has(previous.id) || consumedPriorIds.has(previous.id) || !previous.decision || previous.decision === "pending") continue;
+    const committed = previous.origin === "committed" || previous.origin === "promoted-validated" || previous.generation?.status === "promoted";
+    // A decided proposal whose scope is no longer derived duplicates the surviving same-name
+    // decision — drop the duplicate rather than carrying it as stale forever. If that scope is
+    // re-derived later, its proposals return as pending review; the failure direction is more
+    // human review, never a silently granted decision. Committed/promoted items always carry.
+    if (!committed && !derivedScopes.has(previous.scope || ".") && survivorNames.has(previous.name)) continue;
+    carried.push({ ...previous, stale: true, status: "not-derived-on-refresh" });
+  }
   let generation = prior.generation;
   if (invalidateValidation && generation) generation = {
     ...generation,

package/mcp-server/src/index.js

@@ -634,9 +634,9 @@ export function agentFacingElements(elements, limit = 160) {
   return result;
 }
 
-function agentScreenProjection(screen) {
+function agentScreenProjection(screen, { full = false } = {}) {
   const all = screen?.elements || [];
-  const elements = agentFacingElements(all);
+  const elements = full ? all : agentFacingElements(all);
   return {
     screenTitle:screen?.screenTitle ?? null,
     elementCount:elements.length,
@@ -778,16 +778,16 @@ async function firstVisibleWebLocator(page, target, { input = false } = {}) {
   return await fallback.isVisible().catch(() => false) ? fallback : null;
 }
 
-async function startWebSession(url, { testEmail = "", testPassword = "" } = {}) {
+async function startWebSession(url, { testEmail = "", testPassword = "", device = "", viewport = "" } = {}) {
   if (activeSession && !activeSession.ended) return { error: "A session is already active; call tapp_session_end first.", screen:treeSnapshot() };
   let browser;
   try {
     const parsed = new URL(String(url || ""));
     if (!/^https?:$/.test(parsed.protocol)) return { error:"Web session URL must be http(s)" };
-    const { loadPlaywright } = await import("./web-explorer.js");
-    const { chromium } = await loadPlaywright();
+    const { loadPlaywright, webContextOptions } = await import("./web-explorer.js");
+    const { chromium, devices } = await loadPlaywright();
     browser = await chromium.launch({ headless:true });
-    const context = await browser.newContext({ viewport:{ width:1280, height:900 } });
+    const context = await browser.newContext(webContextOptions({ device, viewport, devices }));
     const page = await context.newPage();
     await page.goto(parsed.href, { waitUntil:"domcontentloaded", timeout:30_000 });
     await page.waitForLoadState("networkidle", { timeout:5_000 }).catch(() => {});
@@ -843,22 +843,32 @@ export function isStableFlowCheckpoint(value) {
   const text = String(value || "").replace(/\s+/g, " ").trim();
   if (!text || /^(loading|fetching|please wait|preparing|connecting|syncing|signing in)(?:[.…!]*|\s.*)$/i.test(text)) return false;
   if (/^(?:mon|tues?|wed(?:nes)?|thu(?:rs)?|fri|sat(?:ur)?|sun)(?:day)?\b/i.test(text)) return false;
-  if (/^(?:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|jun(?:e)?|jul(?:y)?|aug(?:ust)?|sep(?:tember)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)\s+\d{1,2}(?:,\s+\d{4})?$/i.test(text)) return false;
+  // Single dates ("Aug 16, 2026") and date ranges ("AUG 16 - AUG 22, 2026") both roll over on
+  // the calendar, so neither is a stable replay checkpoint.
+  const monthDay = "(?:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|jun(?:e)?|jul(?:y)?|aug(?:ust)?|sep(?:tember)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)\\s+\\d{1,2}";
+  if (new RegExp(`^${monthDay}(?:,\\s+\\d{4})?(?:\\s*[-–—]\\s*(?:${monthDay}|\\d{1,2})(?:,\\s+\\d{4})?)?$`, "i").test(text)) return false;
   if (/^\d{4}-\d{2}-\d{2}(?:[ T].*)?$/.test(text)) return false;
   return true;
 }
 
 export function semanticTargetAtPoint(elements, x, y) {
   if (!Number.isFinite(x) || !Number.isFinite(y)) return "";
-  return (elements || [])
+  const containing = (elements || [])
     .filter((element) => {
       const frame = element.frame || {};
-      return element.hittable !== false && Number.isFinite(frame.x) && Number.isFinite(frame.y) && Number.isFinite(frame.width) && Number.isFinite(frame.height)
+      return Number.isFinite(frame.x) && Number.isFinite(frame.y) && Number.isFinite(frame.width) && Number.isFinite(frame.height)
         && x >= frame.x && y >= frame.y && x <= frame.x + frame.width && y <= frame.y + frame.height
         && String(element.id || element.identifier || element.label || "").trim();
     })
-    .sort((a, b) => (a.frame.width * a.frame.height) - (b.frame.width * b.frame.height))
-    .map((element) => String(element.id || element.identifier || element.label || "").trim())[0] || "";
+    .sort((a, b) => (a.frame.width * a.frame.height) - (b.frame.width * b.frame.height));
+  // Prefer a hittable match. A labelled control that reports hittable=false at its own
+  // tree-reported center (custom tab bars over safe-area insets do this) still responds to an
+  // element tap, which retries in the harness — so fall back to it rather than firing a raw
+  // coordinate tap that lands on nothing. Containers stay excluded: redirecting a coordinate
+  // tap to the center of a large labelled group would change where the tap lands.
+  const best = containing.find((element) => element.hittable !== false)
+    || containing.find((element) => /button|link|cell|tab|switch|checkbox|toggle|textfield|securetext|textarea|edittext|segmented|menuitem/i.test(`${element.role || ""} ${element.type || ""}`));
+  return best ? String(best.id || best.identifier || best.label || "").trim() : "";
 }
 
 /** Append a Flow step for an act (record-by-doing). Inserts wait_for on screen change for
@@ -1744,7 +1754,7 @@ export function formatScreen(screenTitle, elements) {
 // `tapp` CLI verbs in bin/tapp.js — same pattern as report.js. Keep orchestration HERE so
 // the surfaces can't drift.)
 
-export async function runQaWeb({ url, maxActions, timeout, testEmail, testPassword, baselineFindings, seedRoutes = [], seedTargets = [], watch = false, surface = "mcp", onProgress = () => {} }) {
+export async function runQaWeb({ url, maxActions, timeout, testEmail, testPassword, baselineFindings, seedRoutes = [], seedTargets = [], watch = false, surface = "mcp", onProgress = () => {}, device = "", viewport = "" }) {
   const { storagePreflight } = await import("./environment-preflight.js");
   const storage = storagePreflight(capturesDir);
   if (!storage.ok) return { error: storage.message, details: { environment: "storage", storage } };
@@ -1766,6 +1776,8 @@ export async function runQaWeb({ url, maxActions, timeout, testEmail, testPasswo
       seedTargets,
       watch: watch === true,
       onProgress,
+      device: isNonEmptyString(device) ? device.trim() : "",
+      viewport: isNonEmptyString(viewport) ? viewport.trim() : "",
     });
   } catch (err) {
     return { error: String(err.message || err) };
@@ -2258,8 +2270,21 @@ export async function startManagedWebTarget({ root, requestedTarget = "", timeou
   const dependencies = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
   const declaredPort = startMatch ? declaredPortFromStartScript(pkg.scripts?.[startMatch[1]]) : 0;
   const frameworkPort = declaredPort ? 0 : managedWebDefaultPort(dependencies);
-  const port = declaredPort || (frameworkPort && await localPortAvailable(frameworkPort) ? frameworkPort : await openLocalPort());
-  const portBasis = declaredPort ? "repository-declared" : port === frameworkPort ? "framework-default" : "available-ephemeral";
+  // An explicit `.tapp/project.json` web.port pin outranks everything: backends with a CORS
+  // allowlist need the managed origin to be exact, so a busy pinned port is a hard error, never
+  // a silent ephemeral fallback that would resurface as fetch/CORS findings.
+  const { readProjectConfig } = await import("./project-config.js");
+  const projectConfig = readProjectConfig(root);
+  if (projectConfig.exists && projectConfig.errors.length) return { error: `Invalid ${projectConfig.relativePath}: ${projectConfig.errors.join("; ")}` };
+  const pinnedPort = Number(projectConfig.config?.web?.port) || 0;
+  if (pinnedPort && declaredPort && pinnedPort !== declaredPort) {
+    return { error: `${projectConfig.relativePath} pins the managed web port to ${pinnedPort}, but the repository start script declares port ${declaredPort}`, details: { remediation: "Align web.port with the start script (or remove one of them) so the managed origin is unambiguous." } };
+  }
+  if (pinnedPort && !(await localPortAvailable(pinnedPort))) {
+    return { error: `${projectConfig.relativePath} pins the managed web port to ${pinnedPort}, but that port is already in use`, details: { remediation: "Stop the process holding the port, change web.port, or provide an already-running owned --url." } };
+  }
+  const port = pinnedPort || declaredPort || (frameworkPort && await localPortAvailable(frameworkPort) ? frameworkPort : await openLocalPort());
+  const portBasis = pinnedPort ? "project-pinned" : declaredPort ? "repository-declared" : port === frameworkPort ? "framework-default" : "available-ephemeral";
   let command = "npm";
   let startArgs;
   let startDir = projectDir;
@@ -2579,6 +2604,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           clearData: { type: "boolean", default: true, description: "Android: clear app data before launch for a repeatable starting state." },
           url: { type: "string", description: "Web (beta): URL of the app to explore in a real browser (same-origin only; your own app/staging). Provide exactly one of appBundleId | url." },
           watch: { type: "boolean", default: false, description: "Web only: open Tapp's controlled Chromium window and show a cursor/HUD for each exploration action. Evidence screenshots exclude the overlay." },
+          device: { type: "string", description: "Web only: render as a Playwright device profile (e.g. \"iPhone 13\") — viewport, user agent, touch" },
+          viewport: { type: "string", description: "Web only: explicit viewport WIDTHxHEIGHT (e.g. \"390x844\"); overrides the device profile's viewport" },
           maxActions: { type: "integer", minimum: 1, maximum: 1000, default: 60, description: "Exploration action budget" },
           timeout: { type: "integer", minimum: 30, maximum: 3600, default: 600, description: "Max wall-clock seconds" },
           testEmail: { type: "string", description: "Email for the login preamble, if the app has a sign-in" },
@@ -2846,7 +2873,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         "Opt-in AI assertion: {assert_ai: '<claim about the current screen>'} (judged host-side; needs a key; " +
         "skipped otherwise). Pass a flow inline via `flow`, or a repo-relative `flowPath` to a .yml/.json. " +
         "A failed assertion fails the flow and is reported like a QA finding. $TEST_EMAIL/$TEST_PASSWORD and any " +
-        "flow `vars` are substituted; pass testEmail/testPassword for real credential values.",
+        "flow `vars` are substituted; pass testEmail/testPassword for real credential values, or `actor` to " +
+        "resolve them from a configured actor's environment-variable bindings.",
       inputSchema: {
         type: "object",
         properties: {
@@ -2865,6 +2893,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           androidSerial: { type: "string", description: "Android adb device serial." },
           testEmail: { type: "string", description: "Value for $TEST_EMAIL" },
           testPassword: { type: "string", description: "Value for $TEST_PASSWORD" },
+          actor: { type: "string", description: "Configured actor name; resolves $TEST_EMAIL/$TEST_PASSWORD from the actor's env-var bindings (explicit testEmail/testPassword win)" },
+          device: { type: "string", description: "Web flows: replay in a Playwright device profile (e.g. \"iPhone 13\")" },
+          viewport: { type: "string", description: "Web flows: explicit viewport WIDTHxHEIGHT (e.g. \"390x844\")" },
         },
       },
     },
@@ -3040,7 +3071,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         "launch per action. Returns the initial screen {screenTitle, elements[]}. Drive it with " +
         "tapp_focus for any named destination (source + shortest observed route), then tapp_session_act only for remaining actions; finish with tapp_session_end. " +
         "For a focused user request, ALWAYS pass it in `focus` so the session reaches that surface before returning. Only one session at a time. Starts from a " +
-        "fresh launch. Use appLaunchArgs/appLaunchEnv for apps that need a backend override or login bypass. " +
+        "fresh COLD launch (terminate + relaunch, for a deterministic starting screen): persisted data such as Keychain credentials survives, but the app opens on its " +
+        "launch screen, NOT a resumed foreground state — an app that gates each cold start behind sign-in will show its login wall, so plan a `login` act (or a login bypass " +
+        "launch argument) as the first step. CLI `tapp tree`/`tapp screenshot` warm-resume the currently foregrounded app instead, which is why they can look signed-in when a session does not. " +
+        "Use appLaunchArgs/appLaunchEnv for apps that need a backend override or login bypass. " +
         "When you reach a screen with input fields and don't have values for them, ASK THE USER what to type " +
         "(offer defaults/skip) before typing — the session does not prompt on its own.",
       inputSchema: {
@@ -3050,6 +3084,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           appBundleId: { type: "string", description: "Bundle id of the installed app to drive" },
           androidAppId: { type: "string", description: "Android application id to drive (alternative to appBundleId)" },
           url: { type: "string", description: "Owned http(s) web app URL to drive (alternative to appBundleId/androidAppId); omit all three target identifiers to build/start an unambiguous owned web target from projectDir" },
+          device: { type: "string", description: "Web sessions: render as a Playwright device profile (e.g. \"iPhone 13\")" },
+          viewport: { type: "string", description: "Web sessions: explicit viewport WIDTHxHEIGHT (e.g. \"390x844\")" },
           target: { type: "string", description: "Optional managed-web target name/path when projectDir contains multiple browser applications" },
           apkPath: { type: "string", description: "Android APK to install before starting" },
           androidSerial: { type: "string", description: "Android adb device serial" },
@@ -3091,8 +3127,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         "on refocus, so step-by-step login flows lose the password), 'tap' (by `id` = accessibility identifier " +
         "or visible/partial label or placeholder, or by `x`/`y` coordinates), 'type' (`text`, optional `id` to " +
         "target a field — always REPLACES the field's content), 'swipe' (`direction`), 'back', 'wait' (block " +
-        "until an element with `id`/`text` appears, up to `timeoutMs`), 'tree' (re-inspect without acting), " +
-        "'screenshot'. Returns {status, screenTitle, elements[]}; status 'not_found'/'timeout'/'still_on_login' " +
+        "until an element with `id`/`text` appears, up to `timeoutMs`), 'tree' (re-inspect without acting; " +
+        "pass `full: true` for every raw element with frames — the default projection dedupes and caps at " +
+        "160 elements, so grep-style checks against it can miss text that IS on screen), " +
+        "'screenshot'. Returns {status, screenTitle, elements[], durationMs}; status 'not_found'/'timeout'/'still_on_login' " +
         "etc. with a `detail` explaining login failures.",
       inputSchema: {
         type: "object",
@@ -3107,6 +3145,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           text: { type: "string", description: "Text to type, or the label/text to wait for" },
           direction: { type: "string", enum: ["up", "down", "left", "right"], description: "Swipe direction" },
           timeoutMs: { type: "integer", minimum: 500, maximum: 60000, default: 5000, description: "For 'wait': how long to poll for the element" },
+          full: { type: "boolean", default: false, description: "For 'tree': return the complete raw element list (frames included) instead of the deduplicated agent-facing projection capped at 160 elements" },
           label: { type: "string", description: "Optional screenshot label" },
         },
         required: ["action"],
@@ -3413,6 +3452,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         testPassword: args.testPassword,
         baselineFindings: args.baselineFindings,
         watch: args.watch === true,
+        device: isNonEmptyString(args.device) ? args.device.trim() : "",
+        viewport: isNonEmptyString(args.viewport) ? args.viewport.trim() : "",
         onProgress: notifyProgress("pages reached"),
       });
       if (r.error) return errorResult(r.error, r.details || {});
@@ -3927,6 +3968,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const runEnv = { ...process.env, FLOW_LOG: flowLog, TAPP_FLOW_EVIDENCE_DIR: evidenceDir };
     if (isNonEmptyString(args.testEmail)) runEnv.OCQA_TEST_EMAIL = args.testEmail.trim();
     if (isNonEmptyString(args.testPassword)) runEnv.OCQA_TEST_PASSWORD = args.testPassword.trim();
+    if (isNonEmptyString(args.actor)) {
+      const { readProjectConfig } = await import("./project-config.js");
+      const loaded = readProjectConfig(workspaceRoot);
+      if (loaded.errors.length) return errorResult(`Invalid ${loaded.relativePath}: ${loaded.errors.join("; ")}`);
+      const actor = loaded.config.actors?.[args.actor.trim()];
+      if (!actor) return errorResult(`Actor '${args.actor.trim()}' is not configured in ${loaded.relativePath}`, { hint: "Configure it with tapp_actor_set / tapp actor set first" });
+      // Actors store env-var NAMES only; resolve values here. Explicit testEmail/testPassword win.
+      for (const [credential, argName, envKey] of [["email", "testEmail", "OCQA_TEST_EMAIL"], ["password", "testPassword", "OCQA_TEST_PASSWORD"]]) {
+        if (isNonEmptyString(args[argName])) continue;
+        const binding = actor.credentials?.[credential];
+        if (!binding) continue;
+        const value = process.env[binding.env];
+        if (!value) return errorResult(`Actor '${args.actor.trim()}' binds ${credential} to $${binding.env}, but that environment variable is not set in the MCP server's environment.`);
+        runEnv[envKey] = value;
+      }
+    }
     let run = { stdout: "", stderr: "", code: 0 };
     if (platform === "web") {
       try {
@@ -3936,6 +3993,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           url: isNonEmptyString(args.url) ? args.url.trim() : undefined,
           logPath: flowLog,
           screenshotDir: evidenceDir,
+          device: isNonEmptyString(args.device) ? args.device.trim() : "",
+          viewport: isNonEmptyString(args.viewport) ? args.viewport.trim() : "",
         });
         run = { ...run, code: result.passed ? 0 : 1, evidenceDir };
       } catch (error) {
@@ -4287,7 +4346,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       : android
         ? await startAndroidSession(target, { serial: args.androidSerial, apkPath: args.apkPath, clearData: args.clearData !== false, testEmail: args.testEmail, testPassword: args.testPassword })
         : web
-          ? await startWebSession(target, { testEmail:args.testEmail, testPassword:args.testPassword })
+          ? await startWebSession(target, { testEmail:args.testEmail, testPassword:args.testPassword, device:isNonEmptyString(args.device) ? args.device.trim() : "", viewport:isNonEmptyString(args.viewport) ? args.viewport.trim() : "" })
           : await startManagedWebInteractiveSession({
               projectDir:focusProjectDir,
               requestedTarget:isNonEmptyString(args.target) ? args.target.trim() : "",
@@ -4376,7 +4435,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const detailNote = !ok && r.detail ? ` — ${r.detail}` : "";
     const head = `${did} — ${ok ? "ok" : `⚠️ ${r.status}${detailNote}`} → now on **${r.screenTitle || "Unknown"}**`;
     const rec = typeof r.recordedSteps === "number" ? `\n\n🔴 Recording — ${r.recordedSteps} step(s). \`tapp_flow_save\` to keep it as a test.` : "";
-    const screen = agentScreenProjection(r);
+    const screen = agentScreenProjection(r, { full: action === "tree" && args.full === true });
     const result = richResult(head + "\n\n" + formatScreen(screen.screenTitle, screen.elements) + rec, { ...r, ...screen });
     if (!ok) result.isError = true;
     return result;

package/mcp-server/src/project-config.js

@@ -22,7 +22,7 @@ function cleanActor(actor) {
 export function validateProjectConfig(config) {
   const errors = [];
   if (!config || typeof config !== "object" || Array.isArray(config)) return ["Project configuration must be an object"];
-  for (const key of Object.keys(config)) if (!["kind", "schemaVersion", "actors", "lifecycle", "provenance"].includes(key)) errors.push(`unsupported project configuration field '${key}'`);
+  for (const key of Object.keys(config)) if (!["kind", "schemaVersion", "actors", "lifecycle", "provenance", "web"].includes(key)) errors.push(`unsupported project configuration field '${key}'`);
   if (config.kind !== "tapp-project-config") errors.push("kind must be 'tapp-project-config'");
   if (config.schemaVersion !== 1) errors.push("schemaVersion must be 1");
   if (config.actors !== undefined && (!config.actors || typeof config.actors !== "object" || Array.isArray(config.actors))) errors.push("actors must be an object");
@@ -43,6 +43,13 @@ export function validateProjectConfig(config) {
       for (const key of Object.keys(binding || {})) if (key !== "env") errors.push(`actor '${name}' credential '${credential}' may contain only env; credential values are forbidden`);
     }
   }
+  if (config.web !== undefined) {
+    if (!config.web || typeof config.web !== "object" || Array.isArray(config.web)) errors.push("web must be an object");
+    else {
+      for (const key of Object.keys(config.web)) if (key !== "port") errors.push(`web has unsupported field '${key}'; the managed web host is always 127.0.0.1`);
+      if (config.web.port !== undefined && (!Number.isInteger(config.web.port) || config.web.port < 1 || config.web.port > 65535)) errors.push("web.port must be an integer between 1 and 65535");
+    }
+  }
   if (config.lifecycle !== undefined && (!config.lifecycle || typeof config.lifecycle !== "object" || Array.isArray(config.lifecycle))) errors.push("lifecycle must be an object");
   for (const key of Object.keys(config.lifecycle || {})) if (!["setup", "teardown"].includes(key)) errors.push(`lifecycle has unsupported phase '${key}'`);
   if (config.provenance !== undefined && (!config.provenance || typeof config.provenance !== "object" || Array.isArray(config.provenance))) errors.push("provenance must be an object");

package/mcp-server/src/report.js

@@ -72,6 +72,7 @@ export function parseOcqaMarkers(markersFilePath) {
       )
     ),
     complete,
+    actions,
     recentActions: actions.slice(-5),
     recentTransitions: transitions.slice(-5),
     recentIssues: issues.slice(-5),
@@ -87,6 +88,10 @@ export const ISSUE_CATEGORY = {
   error_surface: "network_error_surface",
   unresponsive_element: "unresponsive_element",
   placeholder_link: "broken_link",
+  anchor_missing: "broken_link",
+  unresolvable_host: "broken_link",
+  mailto_no_mx: "broken_link",
+  outbound_unavailable: "broken_link",
   dead_end: "navigation_dead_end",
   navigation_loop: "repeated_loop",
   navigation_trap: "navigation_dead_end",
@@ -96,7 +101,7 @@ export const ISSUE_CATEGORY = {
   explore_timeout: "performance_timeout",
 };
 export const CRITICAL_ISSUE_TYPES = new Set(["crash"]);
-export const WEB_SAMPLED_ISSUE_TYPES = new Set(["unresponsive_element"]);
+export const WEB_SAMPLED_ISSUE_TYPES = new Set(["unresponsive_element", "outbound_unavailable"]);
 
 export function severityRank(s) {
   return { critical: 0, high: 1, medium: 2, low: 3 }[s] ?? 4;
@@ -206,7 +211,9 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
   // keep the concrete missing-asset finding and discard that transport-level duplicate.
   const normalizedIssues = rawIssues.map((issue) => {
     if (platform !== "web") return issue;
-    if (issue.type === "placeholder_link" && issue.target) return { ...issue, screen: null };
+    if (["placeholder_link", "anchor_missing", "unresolvable_host", "mailto_no_mx", "outbound_unavailable"].includes(issue.type) && issue.target) {
+      return { ...issue, screen: null };
+    }
     if (!["missing_asset", "network_error"].includes(issue.type)) return issue;
     const title = String(issue.title || "");
     const match = issue.type === "missing_asset"
@@ -279,9 +286,16 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
     : screensExplored >= 2 && actionsPerformed >= 3;
   const unexercisedLoginWall = anySecure && !loginAttempted && screensExplored <= 1;
   const inconclusive = !coverageFloorMet || unexercisedLoginWall || timeBudgetExhausted;
+  // "completed" is reserved for a run that exhausted its action budget; a drained frontier is
+  // reported as its own honest reason so a 2-action sweep of a small surface never reads like a
+  // 40-action campaign. Drivers signal the real cause in COMPLETE.stop; captures from drivers
+  // that predate the field keep the old inference.
+  const driverStop = base.complete && typeof base.complete === "object" ? base.complete.stop : null;
   const stopReason = unexercisedLoginWall ? (credentialsProvided ? "login-wall-credentials-unused" : "login-wall-no-credentials")
     : timeBudgetExhausted ? "time-budget-exhausted"
-    : coverageFloorMet ? "completed" : "coverage-floor-not-met";
+    : !coverageFloorMet ? "coverage-floor-not-met"
+    : driverStop === "frontier-drained" ? "no-unexplored-in-scope-controls"
+    : "completed";
 
   const headline = timeBudgetExhausted
     ? `Inconclusive — exploration reached its ${base.complete?.timeoutSeconds || "configured"}s time budget after ${actionsPerformed} action(s) across ${screensExplored} screen(s). Findings are partial; this is not an app performance finding. Increase --timeout or request fewer actions.`
@@ -301,10 +315,17 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
   let checkedFor;
   let notChecked;
   if (platform === "web") {
+    const outbound = base.complete && typeof base.complete === "object" ? base.complete.outbound : null;
     checkedFor = [
-      "page errors (uncaught exceptions)", "failed/5xx requests", "broken links (404)",
-      "placeholder links with no destination", "sampled dead-button probes (advisory)", "error text on pages", "load timeouts",
+      "page errors (uncaught exceptions)", "failed/5xx requests", "broken links (404, same-origin crawl)",
+      "placeholder links and anchors with no destination", "sampled dead-button probes (advisory)", "error text on pages", "load timeouts",
     ];
+    if (outbound && !outbound.skipped && (outbound.total || outbound.mailtos)) {
+      checkedFor.push(outbound.total > outbound.checked
+        ? `outbound link reachability — DNS · HTTP · unavailable-shell heuristic (first ${outbound.checked} of ${outbound.total})`
+        : "outbound link reachability (DNS · HTTP · unavailable-shell heuristic)");
+      if (outbound.mailtos) checkedFor.push("mailto address domains (MX/A records)");
+    }
     notChecked = [
       "app-specific business logic (cover with Flows: record or generate, then assert)",
       "content and claim accuracy (including copy versus API data)",
@@ -314,6 +335,11 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
       "only the first few visible buttons per page are probed (web beta)",
       "content & reachability regressions require a baseline",
     ];
+    if (outbound?.skipped === "egress-policy") notChecked.push("outbound links and mailto domains (skipped by the public-egress policy)");
+    else if (!outbound || (!outbound.total && !outbound.mailtos)) conditionsNotReached.push("outbound links (none encountered this run)");
+    if (inputFieldsEncountered.length && !loginAttempted) {
+      notChecked.push(`form submission (${inputFieldsEncountered.reduce((n, s) => n + s.fields.length, 0)} field(s) catalogued, none submitted)`);
+    }
   } else if (platform === "android") {
     checkedFor = [
       "crashes / process exits", "dead controls", "error surfaces", "blank screens",
@@ -361,6 +387,18 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
     headline,
     inconclusive,
     coverage: { screensExplored, actionsPerformed, screens: Array.from(screens) },
+    // Per-action evidence: what was done, to what, on which screen, at what offset — so an
+    // agent can distinguish "clicked Services, clicked FAQ" from "clicked the same button twice".
+    trace: (base.actions || [])
+      .filter((action) => action && typeof action === "object")
+      .map((action) => ({
+        ...(typeof action.t === "number" ? { t: action.t } : {}),
+        type: action.type || "action",
+        target: action.target || "",
+        ...(action.screen ? { screen: action.screen } : {}),
+        ...(action.via ? { via: action.via } : {}),
+        ...(action.reason ? { reason: action.reason } : {}),
+      })),
     evidence: { markers: base.relativeMarkersFilePath },
     uiMap: null,
     comparison: null,

package/mcp-server/src/web-explorer.js

@@ -23,6 +23,7 @@ import { execFileSync } from "child_process";
 const CLICK_SETTLE_MS = 700;
 const NAV_TIMEOUT_MS = 15_000;
 const BUTTONS_PER_PAGE = 4;
+const OUTBOUND_LINK_LIMIT = 10;
 const WATCH_ACTION_DELAY_MS = 350;
 const ERROR_TEXT_RE = /\b(something went wrong|internal server error|an error occurred|failed to load|unhandled exception)\b/i;
 const STANDALONE_ERROR_TEXT_RE = /^(something went wrong|internal server error|an error occurred|failed to load|unhandled exception)(?:[.!:]|\s|$)/i;
@@ -299,6 +300,42 @@ export function webBrowserLaunchOptions(environment = process.env, { watch = fal
   };
 }
 
+export function parseWebViewport(value) {
+  if (!value) return null;
+  const match = /^(\d{2,5})[xX](\d{2,5})$/.exec(String(value).trim());
+  if (!match) throw new Error(`Invalid viewport '${value}'; expected WIDTHxHEIGHT, e.g. 390x844`);
+  return { width: Number(match[1]), height: Number(match[2]) };
+}
+
+// The one seam for every web browser context: an optional Playwright device profile (viewport,
+// user agent, touch, scale factor) with an explicit WIDTHxHEIGHT override on top; the historical
+// 1280×900 desktop default otherwise. `defaultBrowserType` is stripped because newContext
+// rejects it — we always drive the profile through chromium.
+export function webContextOptions({ device = "", viewport = "", devices = null } = {}) {
+  const name = String(device || "").trim();
+  let base = {};
+  if (name) {
+    const profile = devices ? devices[name] : null;
+    if (!profile) {
+      const head = name.toLowerCase().split(" ")[0];
+      const close = devices ? Object.keys(devices).filter((d) => d.toLowerCase().includes(head)).slice(0, 5) : [];
+      throw new Error(`Unknown Playwright device '${name}'${close.length ? `; close matches: ${close.join(", ")}` : ""}`);
+    }
+    const { defaultBrowserType: _ignored, ...rest } = profile;
+    base = rest;
+  }
+  const parsed = parseWebViewport(viewport);
+  return { ...base, viewport: parsed || base.viewport || { width: 1280, height: 900 } };
+}
+
+// Conservative "the page answered 200 but is an unavailable shell" phrases (outbound links to
+// social platforms that never 404). Precision over recall: only unmistakable copy matches.
+export function webUnavailableShellPhrase(html) {
+  const text = String(html || "").slice(0, 120_000);
+  const match = /(this content isn'?t available|content (?:is )?(?:currently )?unavailable|this page isn'?t available|page (?:can'?t|cannot) be found|page not found|isn'?t available right now)/i.exec(text);
+  return match ? match[1] : null;
+}
+
 // A headed Playwright browser does not move the host OS pointer when locator.click() runs. In
 // explicit watch mode, draw a pointer inside the controlled page so a human can follow Tapp's
 // real actions. The UI lives in a closed shadow root, ignores pointer events, and is hidden from
@@ -398,16 +435,16 @@ async function screenshotWithoutWebWatchUi(page, options, watch) {
 // Focused one-screen inspection for the agent-facing `tapp open <url>` and `tapp tree <url>`
 // commands. This deliberately does no exploration or judgment; it opens exactly one page,
 // captures the visible semantic controls, and optionally takes one screenshot.
-export async function inspectWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, screenshot = true, tapText = "", waitForText = "" }) {
+export async function inspectWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, screenshot = true, tapText = "", waitForText = "", device = "", viewport = "", fullPage = false }) {
   let target;
   try { target = new URL(url); }
   catch { throw new Error("Web inspection needs a valid http(s) URL"); }
   if (!/^https?:$/.test(target.protocol)) throw new Error("Web inspection needs a valid http(s) URL");
 
-  const { chromium } = await loadPlaywright();
+  const { chromium, devices } = await loadPlaywright();
   const browser = await chromium.launch(webBrowserLaunchOptions());
   try {
-    const context = await browser.newContext({ viewport: { width: 1280, height: 900 } });
+    const context = await browser.newContext(webContextOptions({ device, viewport, devices }));
     const page = await context.newPage();
     const boundedTimeout = Math.max(1000, Math.min(60_000, Number(timeoutMs) || NAV_TIMEOUT_MS));
     page.setDefaultTimeout(boundedTimeout);
@@ -455,7 +492,7 @@ export async function inspectWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, screensh
         controls,
       };
     });
-    const image = screenshot ? await page.screenshot({ type: "png" }) : null;
+    const image = screenshot ? await page.screenshot({ type: "png", fullPage: !!fullPage }) : null;
     return {
       url: page.url(),
       screenTitle: webScreenTitle(observed, target.pathname || target.href),
@@ -524,17 +561,19 @@ export function normalizeWebSeedTargets(seedTargets = [], limit = 5) {
   return result;
 }
 
-export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDir, testEmail = "", testPassword = "", seedRoutes = [], seedTargets = [], watch = false, onProgress }) {
+export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDir, testEmail = "", testPassword = "", seedRoutes = [], seedTargets = [], watch = false, onProgress, device = "", viewport = "" }) {
   const start = new URL(url);
   if (!/^https?:$/.test(start.protocol)) throw new Error("url must be http(s)");
   fs.mkdirSync(outDir, { recursive: true });
   const markersPath = path.join(outDir, "ocqa-markers.txt");
   const markersFd = fs.openSync(markersPath, "w");
   const emit = (kind, payload) => fs.writeSync(markersFd, `OCQA_${kind}:${JSON.stringify(payload)}\n`);
+  const startedAtMs = Date.now();
+  const emitAction = (payload) => emit("ACTION", { t: Date.now() - startedAtMs, ...payload });
 
-  const { chromium } = await loadPlaywright();
+  const { chromium, devices } = await loadPlaywright();
   const browser = await chromium.launch(webBrowserLaunchOptions(process.env, { watch }));
-  const context = await browser.newContext({ viewport: { width: 1280, height: 900 } });
+  const context = await browser.newContext(webContextOptions({ device, viewport, devices }));
   await installWebListenerTracking(context);
   if (watch) await installWebWatchUi(context);
   const page = await context.newPage();
@@ -585,6 +624,10 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
   ];
   const screenshotFor = new Map();
   const placeholderLinksSeen = new Set();
+  const missingAnchorsSeen = new Set();
+  const outboundLinks = new Map(); // href → { label, screen }
+  const mailtoLinks = new Map(); // address → { screen }
+  const outbound = { total: 0, checked: 0, mailtos: 0 };
   let actions = 0;
   let screenCount = 0;
   let lastScreen = null;
@@ -607,12 +650,12 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
           secure: el.type === "password",
         }))
         .filter((f) => f.label);
-      const controls = [...document.querySelectorAll("button, a[href], input, textarea, select, [role=button], [role=tab], [role=checkbox], [role=switch]")]
+      const controls = [...document.querySelectorAll("button, a[href], input, textarea, select, summary, [role=button], [role=tab], [role=checkbox], [role=switch]")]
         .filter((el) => el.type !== "hidden" && el.offsetParent !== null)
         .slice(0, 60)
         .map((el) => {
           const tag = el.tagName.toLowerCase();
-          const role = el.getAttribute("role") || (tag === "a" ? "link" : tag === "button" ? "button" : "");
+          const role = el.getAttribute("role") || (tag === "a" ? "link" : tag === "button" || tag === "summary" ? "button" : "");
           const field = ["input", "textarea", "select"].includes(tag);
           const secure = el.type === "password";
           const label = (el.labels?.[0]?.textContent || el.getAttribute("aria-label") || el.textContent || el.placeholder || el.name || el.id || "").trim().slice(0, 120);
@@ -674,6 +717,18 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
               fingerprint: el.id || el.getAttribute("data-testid") || svgPath.slice(0, 80) || `link-${index + 1}`,
             };
           }),
+        missingAnchors: [...document.querySelectorAll('a[href^="#"]')]
+          .filter((el) => el.offsetParent !== null)
+          .map((el) => el.getAttribute("href") || "")
+          .filter((href) => href.length > 1)
+          .filter((href) => {
+            const id = decodeURIComponent(href.slice(1));
+            try {
+              const esc = window.CSS && CSS.escape ? CSS.escape(id) : id;
+              return !document.getElementById(id) && !document.querySelector(`a[name="${esc}"]`);
+            } catch { return !document.getElementById(id); }
+          })
+          .slice(0, 20),
         inputs,
         controls,
       };
@@ -717,6 +772,13 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
         placeholderLinksSeen.add(finding.target);
         issue(finding.type, finding.severity, finding.title, screen, finding.target);
       }
+      // Anchor links pointing at ids that do not exist are deterministic dead navigation.
+      for (const anchor of info.missingAnchors || []) {
+        const anchorTarget = `${key}${anchor}`;
+        if (missingAnchorsSeen.has(anchorTarget)) continue;
+        missingAnchorsSeen.add(anchorTarget);
+        issue("anchor_missing", "medium", `Anchor link "${anchor}" has no matching element on the page`, screen, anchorTarget);
+      }
     }
     return { key, screen, info };
   }
@@ -737,7 +799,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
     if (watch) await showWebWatchAction(page, { locator: pw, action: "Type", target: "Password" });
     await pw.fill(testPassword).catch(() => {});
     lastActionTarget = "Sign in";
-    emit("ACTION", { type: "login", target: "Sign in", screen, narrative: "Filled and submitted the sign-in form with the provided test credentials" });
+    emitAction({ type: "login", target: "Sign in", screen, narrative: "Filled and submitted the sign-in form with the provided test credentials" });
     actions += 1;
     await submitWebLogin(page, watch
       ? (locator) => showWebWatchAction(page, { locator, action: "Click", target: "Sign in" })
@@ -784,7 +846,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
       actions += 1;
       lastActionTarget = webNavigationAction(entry.action, target);
       pendingNavigation = entry.pathTarget ? { ...entry, prTarget: false } : entry;
-      emit("ACTION", { type: "open", target, via: lastActionTarget, narrative: `Opened ${target}` });
+      emitAction({ type: "open", target, via: lastActionTarget, narrative: `Opened ${target}` });
       // Attribute load-time events (pageerror, 404s) to the page being loaded, not the one
       // we just left; observe() refines this to the page title once it settles.
       currentScreen = target;
@@ -814,7 +876,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
           const beforeScreen = ob.screen;
           actions += 1;
           lastActionTarget = action.target;
-          emit("ACTION", { type: action.type, target: action.target, screen: beforeScreen, reason: "pr_ui_map_path", narrative: `Following observed UI Map path: ${action.type} ${action.target}` });
+          emitAction({ type: action.type, target: action.target, screen: beforeScreen, reason: "pr_ui_map_path", narrative: `Following observed UI Map path: ${action.type} ${action.target}` });
           let acted = false;
           if (action.type === "back") {
             if (watch) await showWebWatchAction(page, { action: "Back", target: beforeScreen });
@@ -857,15 +919,27 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
         emit("PR_TARGET", { targetId: entry.targetId, status: "observed", screen: ob.screen });
       }
 
-      // Enqueue unvisited same-origin links (BFS keeps exploration order deterministic).
+      // Enqueue unvisited same-origin links (BFS keeps exploration order deterministic);
+      // collect outbound http(s) links and mailto addresses for the post-crawl audit.
       const links = await page.$$eval("a[href]", (as) => as.map((a) => ({
         href: a.href,
+        raw: a.getAttribute("href") || "",
         label: (a.getAttribute("aria-label") || a.textContent || "").trim(),
       }))).catch(() => []);
       for (const link of links) {
         try {
+          if (/^mailto:/i.test(link.raw)) {
+            const address = link.raw.replace(/^mailto:/i, "").split("?")[0].trim();
+            if (address.includes("@") && !mailtoLinks.has(address)) mailtoLinks.set(address, { screen: ob.screen });
+            continue;
+          }
           const u = new URL(link.href);
-          if (u.origin !== start.origin || !/^https?:$/.test(u.protocol)) continue;
+          if (!/^https?:$/.test(u.protocol)) continue;
+          if (u.origin !== start.origin) {
+            const clean = u.origin + u.pathname;
+            if (!outboundLinks.has(clean)) outboundLinks.set(clean, { label: link.label, screen: ob.screen });
+            continue;
+          }
           const key = u.pathname.replace(/\/+$/, "") + u.search || "/";
           if (!visited.has(key) && !frontier.some((item) => item.target === key)) {
             frontier.push({ target: key, action: webNavigationAction(link.label, key), fromScreen: ob.screen });
@@ -875,7 +949,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
 
       // Bounded button pass: click, watch for effect, flag dead controls (the web analog
       // of the iOS dead-button detector). Navigations are undone so BFS order holds.
-      const buttons = page.locator("button:visible, [role=button]:visible, input[type=submit]:visible");
+      const buttons = page.locator("button:visible, [role=button]:visible, input[type=submit]:visible, summary:visible");
       const n = Math.min(await buttons.count().catch(() => 0), BUTTONS_PER_PAGE);
       for (let i = 0; i < n && actions < maxActions && Date.now() < deadline; i++) {
         const b = buttons.nth(i);
@@ -893,7 +967,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
         const beforeState = await captureWebControlState(page, b);
         actions += 1;
         lastActionTarget = label;
-        emit("ACTION", { type: "tap", target: label, screen: webActionScreen(ob), narrative: `Tapped "${label}"` });
+        emitAction({ type: "tap", target: label, screen: webActionScreen(ob), narrative: `Tapped "${label}"` });
         let clickSucceeded = false;
         try {
           if (watch) await showWebWatchAction(page, { locator: b, action: "Click", target: label });
@@ -925,8 +999,58 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
       }
       progress();
     }
+
+    // Post-crawl outbound audit: DNS + bounded HTTP for external links, MX for mailto.
+    // These calls leave the proxied browser, so the whole pass is skipped (and reported as
+    // not-checked) when the public-egress policy is enforced.
+    outbound.total = outboundLinks.size;
+    outbound.mailtos = mailtoLinks.size;
+    if (process.env.TAPP_ENFORCE_PUBLIC_EGRESS === "1") {
+      outbound.skipped = "egress-policy";
+    } else if (outboundLinks.size || mailtoLinks.size) {
+      const dns = await import("node:dns/promises");
+      const hostResolvable = new Map();
+      const resolves = async (host) => {
+        if (!hostResolvable.has(host)) {
+          hostResolvable.set(host, await dns.lookup(host).then(() => true).catch(() => false));
+        }
+        return hostResolvable.get(host);
+      };
+      const targets = [...outboundLinks.entries()].slice(0, OUTBOUND_LINK_LIMIT);
+      outbound.checked = targets.length;
+      for (const [href, meta] of targets) {
+        if (Date.now() >= deadline) break;
+        const u = new URL(href);
+        if (!(await resolves(u.hostname))) {
+          issue("unresolvable_host", "medium", `Outbound link host does not resolve: ${u.hostname}`, meta.screen, href);
+          continue;
+        }
+        try {
+          const res = await fetch(href, { redirect: "follow", signal: AbortSignal.timeout(6000), headers: { "user-agent": "Mozilla/5.0 (compatible; tapp-link-audit)" } });
+          if (res.status >= 400) {
+            issue("broken_link", "medium", `Outbound link returns HTTP ${res.status}: ${href.slice(0, 100)}`, meta.screen, href);
+          } else {
+            const phrase = webUnavailableShellPhrase(await res.text().catch(() => ""));
+            if (phrase) issue("outbound_unavailable", "low", `Outbound link returns 200 but shows "${phrase}": ${href.slice(0, 100)}`, meta.screen, href);
+          }
+        } catch (error) {
+          issue("unresolvable_host", "medium", `Outbound link unreachable: ${href.slice(0, 100)}`, meta.screen, href);
+        }
+      }
+      for (const [address, meta] of mailtoLinks) {
+        if (Date.now() >= deadline) break;
+        const domain = (address.split("@")[1] || "").toLowerCase();
+        if (!domain) continue;
+        // RFC 5321 implicit-MX: a domain with no MX but an A/AAAA record can still receive.
+        const deliverable = await dns.resolveMx(domain).then((records) => records.length > 0).catch(() => false)
+          || await dns.lookup(domain).then(() => true).catch(() => false);
+        if (!deliverable) issue("mailto_no_mx", "medium", `mailto: domain cannot receive email (no MX or address record): ${address}`, meta.screen, address);
+      }
+    }
   } finally {
-    emit("COMPLETE", { actions, screens: screenCount, credentialsProvided: !!(testEmail || testPassword), credentialsUsed: loginTried });
+    const timedOut = Date.now() >= deadline;
+    const stop = timedOut ? "time-budget" : actions >= maxActions ? "action-budget" : "frontier-drained";
+    emit("COMPLETE", { actions, screens: screenCount, credentialsProvided: !!(testEmail || testPassword), credentialsUsed: loginTried, timedOut, stop, outbound });
     fs.closeSync(markersFd);
     await browser.close().catch(() => {});
   }

package/mcp-server/src/web-flow.js

@@ -3,7 +3,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { FlowLog, flowVariables, normalizeFlowStep, substituteFlowValue } from "./flow-runtime.js";
-import { loadPlaywright } from "./web-explorer.js";
+import { loadPlaywright, webContextOptions } from "./web-explorer.js";
 
 const DEFAULT_TIMEOUT = 6000;
 
@@ -192,7 +192,7 @@ export async function executeWebFlowStep({ page, step, vars = {}, defaultTimeout
   return { action, target: action === "login" ? "sign-in form" : target || value, status, detail, task: raw.task };
 }
 
-export async function runWebFlow({ flow, url, logPath, screenshotDir, playwright }) {
+export async function runWebFlow({ flow, url, logPath, screenshotDir, playwright, device = "", viewport = "" }) {
   const startUrl = url || flow.url || (/^https?:\/\//i.test(flow.app || "") ? flow.app : "");
   if (!startUrl) throw new Error("Web Flow needs `url:` (or an http(s) `app:` value)");
   if (logPath) fs.rmSync(logPath, { force: true });
@@ -202,7 +202,7 @@ export async function runWebFlow({ flow, url, logPath, screenshotDir, playwright
   const log = new FlowLog({ logPath, flow: loggedFlow });
   const pw = playwright || await loadPlaywright();
   const browser = await pw.chromium.launch({ headless: true });
-  const context = await browser.newContext({ viewport: { width: 1280, height: 900 } });
+  const context = await browser.newContext(webContextOptions({ device, viewport, devices: pw.devices }));
   const page = await context.newPage();
   const timeout = Number(flow.timeoutMs) || DEFAULT_TIMEOUT;
   page.setDefaultTimeout(timeout);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.3",
+  "version": "0.17.5",
   "mcpName": "io.github.aarwitz/tapp",
   "description": "Let coding agents verify UI changes on real iOS, Android, and web surfaces, then enforce reviewed proof in deterministic CI.",
   "license": "MIT",
@@ -89,7 +89,7 @@
     "mobile"
   ],
   "scripts": {
-    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/focused-navigation.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/android-primitives-protocol.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/cloud-runner.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/mcp-workspace.test.js tests/action.test.js tests/package-surface.test.js tests/agent-surface.test.js tests/presentation-contract.test.js tests/landing-brand.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js vscode-extension/test/bridge.test.js",
+    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/focused-navigation.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-link-audit.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/android-primitives-protocol.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/cloud-runner.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/mcp-workspace.test.js tests/action.test.js tests/package-surface.test.js tests/agent-surface.test.js tests/presentation-contract.test.js tests/landing-brand.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js vscode-extension/test/bridge.test.js",
     "test:browser-journey": "node --test tests/browser-journey.test.js",
     "test:browser-native": "TAPP_RUN_NATIVE_BROWSER=1 node --test tests/browser-native-journey.test.js"
   }

package/scripts/run-web-flow.js

@@ -18,7 +18,14 @@ const logPath = process.env.FLOW_LOG || path.join(os.tmpdir(), `tapp-web-flow-${
 const screenshotDir = process.env.TAPP_FLOW_EVIDENCE_DIR || path.join(os.tmpdir(), `tapp-web-flow-${token}`);
 
 try {
-  const result = await runWebFlow({ flow, url: process.argv[3], logPath, screenshotDir });
+  const result = await runWebFlow({
+    flow,
+    url: process.argv[3],
+    logPath,
+    screenshotDir,
+    device: process.env.TAPP_WEB_DEVICE || "",
+    viewport: process.env.TAPP_WEB_VIEWPORT || "",
+  });
   const report = spawnSync("python3", [path.join(root, "scripts", "flow_lib.py"), "report", logPath], { encoding: "utf8" });
   process.stdout.write((report.stdout || "").trim() + "\n");
   process.exit(result.passed ? 0 : 1);

package/skills/tapp/references/commands.md

@@ -48,6 +48,11 @@ npx -y @aarwitz/tapp@latest open https://example.com --tap "Not now" --wait-for
 - `tapp_focus`: source-locate a named screen/control and execute the shortest observed route in the active session.
 - `tapp_ui_tree` / `tapp_screenshot`: inspect the current real surface.
 - `tapp_session_start` → `tapp_session_act` → `tapp_session_end`: drive one persistent journey.
+  Sessions begin from a **cold** launch: persisted data survives, but an app that gates each cold
+  start behind sign-in shows its login wall first — make `{action:"login"}` the first act (plain
+  `tapp_ui_tree`/`tapp_screenshot` warm-resume the foregrounded app, so they can look signed-in
+  when a fresh session does not). A `tree` act accepts `full:true` for the complete raw element
+  list when the default ≤160-element projection might omit the text you are checking for.
 - `tapp_explore`: autonomous iOS, Android, or web exploration; observation only.
 - `tapp_flow_save` / `tapp_flow_run`: save a driven journey and replay it deterministically.
 - `tapp_release_contract`: validate, compile, or run a reviewed business guarantee.
@@ -82,6 +87,10 @@ For autonomous exploration, pass test-only values when authorized:
 - CLI: `--email`, `--password`, repeated `--launch-arg`, and JSON `--launch-env`.
 - MCP: `testEmail`, `testPassword`, `inputOverrides`, `appLaunchArgs`, `appLaunchEnv`, or explicit
   `loginSteps`.
+- Reusable: `tapp actor set NAME --email-env ENV --password-env ENV` stores env-var **names**
+  (never values); Flow replay resolves them via `tapp flow run FILE --actor NAME` or
+  `tapp_flow_run {actor:"NAME"}`. Re-running `actor set` on an existing actor requires
+  `--replace` — idempotent setup scripts must include it.
 
 Do not persist secrets in `.tapp/`. If the result reports input fields and no values were supplied,
 ask the user rather than pretending the explored surface was complete.
@@ -95,6 +104,13 @@ npx -y @aarwitz/tapp@latest flow run .tapp/flows/smoke.yml
 npx -y @aarwitz/tapp@latest ci
 ```
 
+Web commands (`open`, `tree`, `explore`, `flow run`) accept `--device "iPhone 13"` (any
+Playwright device profile) or `--viewport 390x844` to render at mobile sizes, and `open`
+accepts `--full-page` for a full-height screenshot — use these for "does it look right on a
+phone" checks. Web explores also audit outbound links (DNS, HTTP status, unavailable-shell
+heuristic) and `mailto:` domains, report an honest `stopReason` (`no-unexplored-in-scope-controls`
+when a small surface is swept before the budget), and return a per-action `trace` in `--json`.
+
 `tapp explore` observes. `tapp ci` applies versioned deterministic policy to evidence, selected
 Flows/Scenarios/contracts, coverage, and any target-scoped baseline. Its outcomes are `pass`, `fail`,
 or `inconclusive`; both `fail` and `inconclusive` block a merge.