@aarwitz/tapp 0.17.0-rc.9 → 0.17.1

package/mcp-server/src/index.js

@@ -9,6 +9,8 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 
@@ -17,7 +19,15 @@ import { existingProjectArtifactPath, projectArtifactDirectory } from "./project
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+// `repoRoot` is the installed Tapp package root: scripts and bundled harness assets live here.
+// Repository-facing MCP operations must use `workspaceRoot` instead. In an npm/Claude-plugin
+// installation those are different directories, even though source-repo tests historically made
+// them look identical.
 const repoRoot = path.resolve(__dirname, "../..");
+const workspaceRoot = (() => {
+  try { return fs.realpathSync(process.cwd()); }
+  catch { return path.resolve(process.cwd()); }
+})();
 const scriptsDir = path.join(repoRoot, "scripts");
 // TAPP_HOME (set by the `tapp` CLI when installed) redirects writable output to a user directory.
 // The old alias remains a read-only fallback; unset repository development stays local.
@@ -35,8 +45,13 @@ function clampOutput(value, maxChars = MAX_OUTPUT_CHARS) {
     return value;
   }
 
-  const dropped = value.length - maxChars;
-  return `${value.slice(0, maxChars)}\n...[truncated ${dropped} chars]`;
+  // Compiler/build diagnostics are normally emitted at the end. Preserve both ends so a long
+  // dependency build cannot truncate away the one actionable error the user needs.
+  const marker = "\n...[output truncated]...\n";
+  const retained = Math.max(0, maxChars - marker.length);
+  const head = Math.ceil(retained / 2);
+  const tail = Math.floor(retained / 2);
+  return `${value.slice(0, head)}${marker}${value.slice(value.length - tail)}`;
 }
 
 function asBoolean(value, fallback = false) {
@@ -320,6 +335,9 @@ export function findXcodeContainer(startDir) {
 }
 
 export async function buildAppForSim({ dir, container, scheme, configuration = "Debug" } = {}) {
+  const { storagePreflight } = await import("./environment-preflight.js");
+  const storage = storagePreflight(path.join(tappHome || os.tmpdir(), "app-builds"));
+  if (!storage.ok) return { error: storage.message, details: { environment: "storage", storage } };
   const target = container || findXcodeContainer(dir || process.cwd());
   if (!target) return { error: `No Xcode project or workspace found under ${dir || process.cwd()}` };
   const isWorkspace = target.endsWith(".xcworkspace");
@@ -539,9 +557,59 @@ function treeSnapshot() {
     screenTitle: t ? t.screenTitle ?? null : null,
     elementCount: t ? (t.elements || []).length : 0,
     elements: t ? t.elements || [] : [],
+    ...(t?.url ? { url:t.url } : {}),
+  };
+}
+
+/** Keep the semantic/actionable accessibility surface an agent needs, without sending hundreds
+ * of empty native hierarchy containers on every turn. The complete tree remains in the active
+ * session for selector resolution; this is only the public MCP projection. */
+export function agentFacingElements(elements, limit = 160) {
+  const result = [];
+  const seen = new Set();
+  for (const element of elements || []) {
+    const semanticValues = [
+      element?.id, element?.identifier, element?.label, element?.text,
+      element?.description, element?.placeholder, element?.value,
+    ].map((value) => String(value ?? "").trim()).filter(Boolean);
+    const roleAndType = `${element?.role || ""} ${element?.type || ""}`.toLowerCase();
+    // Unlabelled input/button controls are still actionable by coordinate. Empty windows,
+    // applications, groups, images and generic containers are implementation noise.
+    const actionableWithoutText = /button|link|textfield|securetext|textarea|edittext|switch|checkbox/.test(roleAndType);
+    if (!semanticValues.length && !actionableWithoutText) continue;
+    const frame = element?.frame || {};
+    const key = JSON.stringify([
+      roleAndType, ...semanticValues,
+      element?.x ?? frame.x ?? null, element?.y ?? frame.y ?? null,
+      element?.w ?? frame.width ?? null, element?.h ?? frame.height ?? null,
+    ]);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(element);
+    if (result.length >= Math.max(1, limit)) break;
+  }
+  return result;
+}
+
+function agentScreenProjection(screen) {
+  const all = screen?.elements || [];
+  const elements = agentFacingElements(all);
+  return {
+    screenTitle:screen?.screenTitle ?? null,
+    elementCount:elements.length,
+    totalElementCount:all.length,
+    elementsOmitted:Math.max(0, all.length - elements.length),
+    elements,
+    ...(screen?.url ? { url:screen.url } : {}),
   };
 }
 
+function focusMetadata(result) {
+  if (!result) return null;
+  const { elements:_elements, elementCount:_elementCount, screenTitle:_screenTitle, url:_url, ...metadata } = result;
+  return metadata;
+}
+
 async function startSession(bundleId, extraEnv = {}) {
   if (activeSession && !activeSession.ended) {
     return { error: "A session is already active; call tapp_session_end first.", screen: treeSnapshot() };
@@ -560,7 +628,7 @@ async function startSession(bundleId, extraEnv = {}) {
     env: { ...process.env, ...extraEnv, OCQA_SESSION_CMD_PATH: cmdPath, OCQA_SESSION_RESULT_PATH: resultPath, OCQA_SESSION_TIMEOUT: "7200" },
   });
   activeSession = {
-    proc, bundleId, seq: 0, cmdPath, resultPath, latestTree: null, treeVersion: 0, buffer: "", ready: false, ended: false,
+    platform:"ios", proc, bundleId, seq: 0, cmdPath, resultPath, latestTree: null, treeVersion: 0, buffer: "", ready: false, ended: false,
     // Always-on recorder: each act appends a Flow step; tapp_flow_save snapshots it to a file.
     recording: [],
     creds: { email: extraEnv.OCQA_TEST_EMAIL || "", password: extraEnv.OCQA_TEST_PASSWORD || "" },
@@ -618,24 +686,26 @@ async function webSessionSnapshot(page) {
       const rect = element.getBoundingClientRect();
       return style.visibility !== "hidden" && style.display !== "none" && rect.width > 0 && rect.height > 0;
     };
-    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,[role=button],[role=tab],[role=checkbox],[role=switch],[role=status],[role=alert],h2,h3,p,li")]
       .filter((element) => element instanceof HTMLElement && visible(element))
       .slice(0, 250)
       .map((element) => {
         const rect = element.getBoundingClientRect();
         const label = String(element.getAttribute("aria-label") || element.labels?.[0]?.textContent || element.textContent || element.getAttribute("placeholder") || element.getAttribute("name") || element.id || "").replace(/\s+/g, " ").trim().slice(0, 160);
+        const interactive = element.matches("button,a[href],input,textarea,select,[role=button],[role=tab],[role=checkbox],[role=switch]");
         return {
           id: element.getAttribute("data-testid") || element.id || element.getAttribute("name") || "",
           label,
           type: element.getAttribute("role") || element.tagName.toLowerCase(),
-          role: element.getAttribute("role") || (element.matches("button,[role=button]") ? "button" : element.matches("a") ? "link" : element.matches("input,textarea,select") ? "input" : "other"),
+          role: element.getAttribute("role") || (element.matches("button,[role=button]") ? "button" : element.matches("a") ? "link" : element.matches("input,textarea,select") ? "input" : "text"),
           enabled: !(element.disabled || element.getAttribute("aria-disabled") === "true"),
-          hittable: true,
+          hittable: interactive,
           clickable: element.matches("button,a,[role=button],[role=tab],[role=checkbox],[role=switch]") && !(element.disabled || element.getAttribute("aria-disabled") === "true"),
           secure: element instanceof HTMLInputElement && element.type === "password",
           frame: { x:Math.round(rect.x), y:Math.round(rect.y), width:Math.round(rect.width), height:Math.round(rect.height) },
         };
-      });
+      })
+      .filter((element) => element.label);
     const heading = document.querySelector("h1,[role=heading]")?.textContent?.replace(/\s+/g, " ").trim();
     return { screenTitle:heading || document.title || location.pathname || "Web application", elements:controls, url:location.href };
   });
@@ -700,6 +770,28 @@ function templateValue(text) {
   return text;
 }
 
+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;
+  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 || [])
+    .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)
+        && 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] || "";
+}
+
 /** Append a Flow step for an act (record-by-doing). Inserts wait_for on screen change for
  *  deterministic replay. Inspection acts (tree/screenshot/wait) are not recorded. */
 function recordStep(cmd, result) {
@@ -710,7 +802,7 @@ function recordStep(cmd, result) {
     case "tap": {
       const target = cmd.id || cmd.label || (typeof cmd.x === "number" ? `${cmd.x},${cmd.y}` : "");
       if (target) activeSession.recording.push({ tap: target });
-      if (changed) activeSession.recording.push({ wait_for: newScreen });
+      if (changed && isStableFlowCheckpoint(newScreen)) activeSession.recording.push({ wait_for: newScreen });
       break;
     }
     case "type": {
@@ -719,12 +811,16 @@ function recordStep(cmd, result) {
       activeSession.recording.push({ type: step });
       break;
     }
+    case "login":
+      activeSession.recording.push({ login: { email: "$TEST_EMAIL", password: "$TEST_PASSWORD" } });
+      if (changed && isStableFlowCheckpoint(newScreen)) activeSession.recording.push({ wait_for: newScreen });
+      break;
     case "swipe":
       activeSession.recording.push({ swipe: cmd.direction || "up" });
       break;
     case "back":
       activeSession.recording.push({ back: true });
-      if (changed) activeSession.recording.push({ wait_for: newScreen });
+      if (changed && isStableFlowCheckpoint(newScreen)) activeSession.recording.push({ wait_for: newScreen });
       break;
     default:
       break; // tree / screenshot / wait are inspection, not test steps
@@ -733,7 +829,17 @@ function recordStep(cmd, result) {
 }
 
 async function sessionAct(cmd) {
-  if (!activeSession || activeSession.ended) return { error: "No active session. Call tapp_session_start first." };
+  const startedAt = Date.now();
+  const done = (result) => ({ ...result, durationMs: Date.now() - startedAt });
+  if (!activeSession || activeSession.ended) return done({ error: "No active session. Call tapp_session_start first." });
+  let coordinateResolvedTarget = "";
+  if (cmd.action === "tap" && !cmd.id && Number.isFinite(cmd.x) && Number.isFinite(cmd.y)) {
+    coordinateResolvedTarget = semanticTargetAtPoint(activeSession.latestTree?.elements, cmd.x, cmd.y);
+    if (coordinateResolvedTarget) {
+      const { x: _x, y: _y, ...semanticCommand } = cmd;
+      cmd = { ...semanticCommand, id: coordinateResolvedTarget };
+    }
+  }
   if (activeSession.platform === "web") {
     const session = activeSession;
     let status = "ok";
@@ -741,9 +847,13 @@ async function sessionAct(cmd) {
     let typedInto = null;
     try {
       if (cmd.action === "tap") {
-        const locator = await firstVisibleWebLocator(session.page, cmd.id || cmd.label || "");
-        if (!locator) { status = "not_found"; detail = "No visible web control matched the semantic target"; }
-        else await locator.click({ timeout:10_000 });
+        const target = cmd.id || cmd.label || "";
+        if (!target && Number.isFinite(cmd.x) && Number.isFinite(cmd.y)) await session.page.mouse.click(cmd.x, cmd.y);
+        else {
+          const locator = await firstVisibleWebLocator(session.page, target);
+          if (!locator) { status = "not_found"; detail = "No visible web control matched the semantic target"; }
+          else await locator.click({ timeout:10_000 });
+        }
       } else if (cmd.action === "type") {
         const locator = await firstVisibleWebLocator(session.page, cmd.id || cmd.label || "", { input:true });
         if (!locator) { status = "not_found"; detail = "No visible web field matched the semantic target"; }
@@ -756,6 +866,28 @@ async function sessionAct(cmd) {
           if (!locator) await session.page.waitForTimeout(120);
         }
         if (!locator) { status = "timeout"; detail = `Timed out waiting for ${cmd.id || cmd.text || "target"}`; }
+      } else if (cmd.action === "login") {
+        const emailValue = cmd.email || session.creds.email || "";
+        const passwordValue = cmd.password || session.creds.password || "";
+        if (!emailValue || !passwordValue) { status = "missing_credentials"; detail = "Email and password are required"; }
+        else {
+          const email = await firstVisibleWebLocator(session.page, "Email", { input:true })
+            || session.page.locator("input[type=email], input[name*=mail i], input[name*=user i], input[id*=mail i], input[id*=user i]").first();
+          const password = session.page.locator("input[type=password]").first();
+          if (!(await email.isVisible().catch(() => false)) || !(await password.isVisible().catch(() => false))) {
+            status = "not_found"; detail = "Could not identify email and password fields";
+          } else {
+            await email.fill(emailValue);
+            await password.fill(passwordValue);
+            const submit = session.page.getByRole("button", { name:/sign in|log in|login|continue|submit/i }).first();
+            if (!(await submit.isVisible().catch(() => false))) { status = "not_found"; detail = "Could not identify a sign-in control"; }
+            else {
+              await submit.click();
+              await session.page.waitForTimeout(500);
+              if (await password.isVisible().catch(() => false)) { status = "still_on_login"; detail = "Submit left the app on the login screen"; }
+            }
+          }
+        }
       } else if (cmd.action === "back") {
         await session.page.goBack({ waitUntil:"domcontentloaded", timeout:10_000 }).catch(() => {});
       } else if (cmd.action === "swipe") {
@@ -774,10 +906,11 @@ async function sessionAct(cmd) {
     }
     const snapshot = treeSnapshot();
     if (status === "ok") recordStep(cmd, snapshot);
-    return { status, typedInto, detail, ...snapshot, recordedSteps:session.recording.length, url:session.latestTree?.url || "" };
+    return done({ status, typedInto, detail, ...snapshot, recordedSteps:session.recording.length, url:session.latestTree?.url || "", ...(coordinateResolvedTarget ? { coordinateResolvedTarget } : {}) });
   }
   if (activeSession.platform === "android") {
     const s = activeSession;
+    const beforeAction = s.latestTree;
     let status = "ok";
     let detail = null;
     let typedInto = null;
@@ -809,28 +942,28 @@ async function sessionAct(cmd) {
           status = "not_found"; detail = "Could not identify email and password fields";
         } else {
           const er = await s.driver.type(emailField.id || emailField.label, cmd.email || s.creds.email || "", s.latestTree);
-          s.latestTree = await s.driver.settle();
+          s.latestTree = await s.driver.settle(2200, s.latestTree);
           const pr = await s.driver.type(passwordField.id || passwordField.label, cmd.password || s.creds.password || "", s.latestTree);
-          s.latestTree = await s.driver.settle();
+          s.latestTree = await s.driver.settle(2200, s.latestTree);
           const submit = s.latestTree.elements.find((e) => e.clickable && /sign in|log in|login|continue/i.test(`${e.text} ${e.label} ${e.id}`));
           if (er.status !== "ok" || pr.status !== "ok" || !submit) {
             status = "not_found"; detail = "Could not fill or submit the login form";
           } else {
             const before = s.latestTree.screenTitle;
             await s.driver.tap(submit.id || submit.description || submit.text, s.latestTree);
-            s.latestTree = await s.driver.settle();
+            s.latestTree = await s.driver.settle(2200, s.latestTree);
             if (s.latestTree.screenTitle === before) { status = "still_on_login"; detail = "Submit left the app on the login screen"; }
           }
         }
       }
-      if (!["wait", "tree", "screenshot", "login"].includes(cmd.action)) s.latestTree = await s.driver.settle();
+      if (!["wait", "tree", "screenshot", "login"].includes(cmd.action)) s.latestTree = await s.driver.settle(2200, beforeAction);
     } catch (error) {
       status = "error"; detail = error.message || String(error);
     }
     s.treeVersion += 1;
     const snap = treeSnapshot();
     if (status === "ok") recordStep(cmd, snap);
-    return { status, typedInto, detail, ...snap, recordedSteps: s.recording.length };
+    return done({ status, typedInto, detail, ...snap, recordedSteps: s.recording.length, ...(coordinateResolvedTarget ? { coordinateResolvedTarget } : {}) });
   }
   activeSession.seq += 1;
   const seq = activeSession.seq;
@@ -859,7 +992,7 @@ async function sessionAct(cmd) {
   while (activeSession.treeVersion === beforeVer && Date.now() < td && !activeSession.ended) await sleep(150);
   const snap = treeSnapshot();
   if (status === "ok") recordStep(cmd, snap); // record only successful acts
-  return { status, typedInto, detail, ...snap, recordedSteps: activeSession ? activeSession.recording.length : 0 };
+  return done({ status, typedInto, detail, ...snap, recordedSteps: activeSession ? activeSession.recording.length : 0, ...(coordinateResolvedTarget ? { coordinateResolvedTarget } : {}) });
 }
 
 async function endSession() {
@@ -904,7 +1037,7 @@ export async function saveInteractiveSessionFlow({ projectDir, name, addFinalAss
   if (!projectDir || !fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error("A valid repository root is required to save a Flow");
   const steps = [...(activeSession.recording || [])];
   if (steps.length === 0) throw new Error("Nothing recorded yet — perform some live-session actions first.");
-  if (addFinalAssertion && activeSession.lastScreen) {
+  if (addFinalAssertion && activeSession.lastScreen && isStableFlowCheckpoint(activeSession.lastScreen)) {
     const last = steps[steps.length - 1] || {};
     if (!("assert_screen" in last)) steps.push({ assert_screen: activeSession.lastScreen });
   }
@@ -946,6 +1079,79 @@ export {
   endSession as endInteractiveSession,
 };
 
+function elementMatchesSemanticTarget(element, value) {
+  const target = String(value || "").trim().toLowerCase();
+  if (!target) return false;
+  return [element?.id, element?.identifier, element?.label, element?.text, element?.description]
+    .map((item) => String(item || "").trim().toLowerCase())
+    .some((item) => item === target || item.includes(target) || target.includes(item));
+}
+
+/** Locate a requested surface from owned source, reconcile it with the runtime-observed UI Map,
+ * and execute the shortest replayable route in the active session. Source may identify intent but
+ * never authorizes a tap: only observed/validated map edges are executed. */
+export async function focusInteractiveSession({ projectDir = process.cwd(), query, platform = "", mapPath = "" } = {}) {
+  const { locateFocusedTarget } = await import("./focused-navigation.js");
+  const sessionPlatform = activeSession?.platform || platform || "";
+  const location = locateFocusedTarget({
+    projectDir, query, platform:sessionPlatform || platform, mapPath,
+    currentScreen:activeSession?.latestTree?.screenTitle || "",
+  });
+  if (!activeSession || activeSession.ended) return { ...location, executed:false, execution:{ status:"not-started", reason:"No active session; start the target app, then focus it." } };
+  if (location.navigation?.status !== "replayable") return { ...location, executed:false, execution:{ status:"blocked", reason:location.navigation?.reason || "No observed route" }, ...treeSnapshot() };
+
+  const executedSteps = [];
+  if (location.navigation.mode === "direct-web-route") {
+    if (activeSession.platform !== "web") return { ...location, executed:false, execution:{ status:"blocked", reason:"A web route cannot be used in a native session" }, ...treeSnapshot() };
+    try {
+      const current = new URL(activeSession.page.url());
+      const destination = new URL(location.navigation.route, current.origin);
+      if (destination.origin !== current.origin) throw new Error("Observed route left the active app origin");
+      await activeSession.page.goto(destination.href, { waitUntil:"domcontentloaded", timeout:15_000 });
+      await activeSession.page.waitForLoadState("networkidle", { timeout:3_000 }).catch(() => {});
+      activeSession.latestTree = await webSessionSnapshot(activeSession.page);
+      activeSession.treeVersion += 1;
+      executedSteps.push({ action:"open", target:location.navigation.route, status:"ok", screenTitle:activeSession.latestTree.screenTitle });
+    } catch (error) {
+      return { ...location, executed:true, execution:{ status:"failed", steps:executedSteps, reason:error.message || String(error) }, ...treeSnapshot() };
+    }
+  } else {
+    for (const step of location.navigation.steps || []) {
+      const action = step.action?.type === "back" ? "back" : "tap";
+      const candidates = [
+        ...(step.action?.selectors || [])
+          .sort((left, right) => {
+            const order = ["testId", "accessibilityId", "resourceId", "cssId", "label"];
+            const rank = (kind) => { const index = order.indexOf(kind); return index < 0 ? order.length : index; };
+            return rank(left.kind) - rank(right.kind);
+          })
+          .map((selector) => selector.value),
+        step.action?.target,
+      ].filter(Boolean);
+      const target = candidates.find((candidate) => (activeSession.latestTree?.elements || []).some((element) => elementMatchesSemanticTarget(element, candidate))) || candidates[0] || "";
+      const result = await sessionAct(action === "back" ? { action } : { action, id:target });
+      executedSteps.push({ action, target, status:result.status, screenTitle:result.screenTitle, durationMs:result.durationMs });
+      if (result.error || result.status !== "ok") return {
+        ...location, executed:true,
+        execution:{ status:"failed", steps:executedSteps, reason:result.error || result.detail || `Observed route step '${target}' did not succeed` },
+        ...treeSnapshot(),
+      };
+    }
+  }
+  const targetControls = location.target?.matchedControls || [];
+  const reachedByTitle = location.target?.name && String(treeSnapshot().screenTitle || "").toLowerCase() === String(location.target.name).toLowerCase();
+  const reachedByControl = targetControls.some((control) => (activeSession.latestTree?.elements || []).some((element) =>
+    [control.id, control.label, control.semanticKey, ...(control.selectors || []).map((selector) => selector.value)].some((value) => elementMatchesSemanticTarget(element, value))
+  ));
+  const reached = reachedByTitle || reachedByControl;
+  return {
+    ...location, executed:true,
+    execution:{ status:reached ? "reached" : "route-completed-unconfirmed", steps:executedSteps,
+      ...(!reached ? { reason:"The observed route completed, but the requested title/control was not visible in the final tree." } : {}) },
+    ...treeSnapshot(),
+  };
+}
+
 export async function captureInteractiveSessionFrame(maxWidth = 900) {
   if (!activeSession || activeSession.ended) return { error:"No active interactive session" };
   if (activeSession.platform === "android") {
@@ -1229,6 +1435,7 @@ export function explorationEnvFromArgs(args) {
   const env = {};
   if (isNonEmptyString(args.testEmail)) env.OCQA_TEST_EMAIL = args.testEmail;
   if (isNonEmptyString(args.testPassword)) env.OCQA_TEST_PASSWORD = args.testPassword;
+  if (isNonEmptyString(args.testEmail) || isNonEmptyString(args.testPassword)) env.OCQA_CREDENTIALS_EXPLICIT = "1";
   if (Array.isArray(args.appLaunchArgs)) {
     const a = args.appLaunchArgs.filter((s) => typeof s === "string" && s.length > 0);
     if (a.length) env.OCQA_APP_LAUNCH_ARGS_JSON = JSON.stringify(a);
@@ -1252,6 +1459,14 @@ export function explorationEnvFromArgs(args) {
   if (args.prExplorationTarget && typeof args.prExplorationTarget === "object" && !Array.isArray(args.prExplorationTarget)) {
     env.OCQA_PR_TARGET_JSON = JSON.stringify(args.prExplorationTarget);
   }
+  // Local visual clients can reveal their preview at the same foreground/settled boundary used by
+  // native recording. Keep this host handshake in the OS temp directory; it is not app evidence or
+  // a caller-directed repository write.
+  if (isNonEmptyString(args.visualReadyPath)) {
+    const readyPath = path.resolve(args.visualReadyPath.trim());
+    const tempRoot = path.resolve(os.tmpdir());
+    if (readyPath.startsWith(`${tempRoot}${path.sep}`)) env.OCQA_VISUAL_READY_PATH = readyPath;
+  }
   // Explicit login replay: a recorded sequence run before exploration, for custom login UIs the
   // heuristic preamble can't parse — the #1 reason a real app stays invisible. Steps are
   // {action: type|tap|wait, target, value?, timeoutMs?}; $TEST_EMAIL/$TEST_PASSWORD substituted
@@ -1320,9 +1535,9 @@ function fmtDuration(ms) {
 export function qaNextSteps(report, surface = "mcp") {
   if (surface === "cli") {
     const next = [];
-    if (report?.findings?.length) next.push("inspect the evidence with `tapp report latest`");
-    next.push("re-run with `--baseline <report.json>` to compare a fix (then `tapp ci` to gate it)");
-    next.push("replay a committed journey with `tapp flow run <file>`");
+    if (report?.findings?.length) next.push("inspect the evidence with `npx -y @aarwitz/tapp@latest report latest`");
+    next.push("save this run with `--json <report.json>`, then re-run with `--baseline <report.json>` to compare a fix (`tapp ci` gates it)");
+    next.push("replay a committed journey with `npx -y @aarwitz/tapp@latest flow run <file>`");
     return next;
   }
   const next = [];
@@ -1344,6 +1559,7 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
   L.push(`### 🔭 Exploration complete — ${badge} · ${observationSummary(report)}${bundleId ? `\n\`${bundleId}\`` : ""}`);
   L.push("");
   L.push(report.headline);
+  if (report.credentialWarning) L.push("", `> ⚠️ ${report.credentialWarning}`);
   L.push("");
   L.push(`**Coverage** — ${report.screensExplored} screens · ${report.actionsPerformed} actions${timedOut ? " · ⏱️ hit time limit" : ""}`);
   if (report.platform === "web") {
@@ -1358,7 +1574,7 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
     L.push("");
     L.push("**Findings**");
     for (const f of report.findings.slice(0, 12)) {
-      L.push(`- ${SEV[f.severity] || "•"} \`${f.severity}\` ${f.title}${f.screen ? ` — on *${f.screen}*` : ""}`);
+      L.push(`- ${SEV[f.severity] || "•"} \`${f.severity}\` ${f.title}${f.screen ? ` — on *${f.screen}*` : ""}${f.url ? ` — ${f.url}` : ""}`);
       if (f.aiAnalysis) L.push(`  - why: ${String(f.aiAnalysis).slice(0, 200)}`);
       if (f.suggestedFix) L.push(`  - fix: ${String(f.suggestedFix).slice(0, 200)}`);
     }
@@ -1375,7 +1591,7 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
     // The merge decision is the gate's job (tapp ci), not exploration's (ADR-0005).
     L.push("");
     L.push(
-      `**Since last run** — +${regression.counts.new} new · ${regression.counts.persisting} persisting · ${regression.counts.resolved} resolved (comparison only — run \`tapp ci\` to gate)`
+      `**Since last run** — +${regression.counts.new} new · ${regression.counts.persisting} persisting · ${regression.counts.resolved} resolved (comparison only — run \`npx -y @aarwitz/tapp@latest ci\` to gate)`
     );
   }
   if (inputHint) {
@@ -1458,7 +1674,10 @@ 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 = [], surface = "mcp", onProgress = () => {} }) {
+export async function runQaWeb({ url, maxActions, timeout, testEmail, testPassword, baselineFindings, seedRoutes = [], seedTargets = [], watch = false, surface = "mcp", onProgress = () => {} }) {
+  const { storagePreflight } = await import("./environment-preflight.js");
+  const storage = storagePreflight(capturesDir);
+  if (!storage.ok) return { error: storage.message, details: { environment: "storage", storage } };
   const actions = Math.max(1, Math.min(1000, asInteger(maxActions, 60)));
   const timeoutSec = Math.max(30, Math.min(3600, asInteger(timeout, 600)));
   const id = "web-" + new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14).replace(/^(\d{8})/, "$1-");
@@ -1475,6 +1694,7 @@ export async function runQaWeb({ url, maxActions, timeout, testEmail, testPasswo
       testPassword: isNonEmptyString(testPassword) ? testPassword.trim() : "",
       seedRoutes,
       seedTargets,
+      watch: watch === true,
       onProgress,
     });
   } catch (err) {
@@ -1500,6 +1720,9 @@ export async function runQaWeb({ url, maxActions, timeout, testEmail, testPasswo
 }
 
 export async function runQaAndroid({ appId, apkPath, serial, maxActions, timeout, testEmail, testPassword, baselineFindings, clearData = true, seedTargets = [], surface = "mcp", onProgress = () => {} }) {
+  const { storagePreflight } = await import("./environment-preflight.js");
+  const storage = storagePreflight(capturesDir);
+  if (!storage.ok) return { error: storage.message, details: { environment: "storage", storage } };
   const actions = Math.max(1, Math.min(1000, asInteger(maxActions, 60)));
   const timeoutSec = Math.max(30, Math.min(3600, asInteger(timeout, 600)));
   const id = "android-" + new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14).replace(/^(\d{8})/, "$1-");
@@ -1543,6 +1766,9 @@ export async function runQaAndroid({ appId, apkPath, serial, maxActions, timeout
 }
 
 export async function runQaIos({ bundleId, maxActions, timeout, args = {}, surface = "mcp", onProgress = () => {} }) {
+  const { storagePreflight } = await import("./environment-preflight.js");
+  const storage = storagePreflight(capturesDir);
+  if (!storage.ok) return { error: storage.message, details: { environment: "storage", storage } };
   const captureScript = path.join(scriptsDir, "quick-capture.sh");
   if (!fs.existsSync(captureScript)) return { error: "Capture script not found", details: { captureScript } };
 
@@ -1635,6 +1861,7 @@ export async function runInitExploration({
   timeout,
   testEmail,
   testPassword,
+  watch = false,
   onProgress = () => {},
   onStatus = () => {},
 } = {}) {
@@ -1650,17 +1877,18 @@ export async function runInitExploration({
   let targetResolution = null;
   let qa;
   let managedRuntime = null;
+  if (watch && selected !== "web") return { error: "Watch mode is currently available for web exploration only." };
   if (selected === "web") {
     if (/^https?:\/\//i.test(String(url))) {
       resolvedTarget = String(url).trim();
-      qa = await runQaWeb({ url: resolvedTarget, maxActions, timeout, testEmail, testPassword, onProgress });
+      qa = await runQaWeb({ url: resolvedTarget, maxActions, timeout, testEmail, testPassword, watch, onProgress });
     } else {
       const started = await startManagedWebTarget({ root, requestedTarget: target, timeout, onStatus });
       if (started.error) return started;
       managedRuntime = started;
       resolvedTarget = started.url;
       try {
-        qa = await runQaWeb({ url: resolvedTarget, maxActions, timeout, testEmail, testPassword, onProgress });
+        qa = await runQaWeb({ url: resolvedTarget, maxActions, timeout, testEmail, testPassword, watch, onProgress });
       } finally {
         await stopManagedWebTarget(started);
       }
@@ -1772,6 +2000,7 @@ export async function runExploreTarget({
   appLaunchArgs,
   appLaunchEnv,
   baselineFindings,
+  watch = false,
   surface = "cli",
   onProgress = () => {},
   onStatus = () => {},
@@ -1782,7 +2011,7 @@ export async function runExploreTarget({
 
   const modelPath = existingProjectArtifactPath(root, "application-model.json");
   if (!fs.existsSync(modelPath)) {
-    return { error: "No application model found — run `tapp init` first, or pass an explicit target (a bundle id, a path/to/App.app, a repo dir, --app-id/--apk, or an http(s) URL)." };
+    return { error: "No application model found — call `tapp_init` or run `npx -y @aarwitz/tapp@latest init` first, or pass an explicit target (a bundle id, a path/to/App.app, a repo dir, --app-id/--apk, or an http(s) URL)." };
   }
   let model;
   try { model = JSON.parse(fs.readFileSync(modelPath, "utf8")); }
@@ -1794,6 +2023,8 @@ export async function runExploreTarget({
   catch (error) { return { error: error.message || String(error) }; }
   const selectedPlatform = selected.platform;
 
+  if (watch && selectedPlatform !== "web") return { error: "Watch mode is currently available for web exploration only." };
+
   if (selectedPlatform !== "ios" && ((Array.isArray(appLaunchArgs) && appLaunchArgs.length) || (appLaunchEnv && Object.keys(appLaunchEnv).length))) {
     return { error: "appLaunchArgs/appLaunchEnv apply only to iOS targets." };
   }
@@ -1802,14 +2033,14 @@ export async function runExploreTarget({
     const ownedUrl = String(selected.runtime?.ownedUrl || "").trim();
     if (/^https?:\/\//i.test(ownedUrl)) {
       onStatus(`Exploring the owned URL from the application model: ${ownedUrl}`);
-      return runQaWeb({ url: ownedUrl, maxActions, timeout, testEmail, testPassword, baselineFindings, surface, onProgress });
+      return runQaWeb({ url: ownedUrl, maxActions, timeout, testEmail, testPassword, baselineFindings, watch, surface, onProgress });
     }
     // Tapp-managed: build/start the repo's web target, wait for readiness, and ALWAYS stop it.
     onStatus(`Preparing the managed web runtime for ${selected.name}…`);
     const started = await startManagedWebTarget({ root, requestedTarget: selected.sourcePath || selected.name || "", timeout, onStatus });
     if (started.error) return started;
     try {
-      return await runQaWeb({ url: started.url, maxActions, timeout, testEmail, testPassword, baselineFindings, surface, onProgress });
+      return await runQaWeb({ url: started.url, maxActions, timeout, testEmail, testPassword, baselineFindings, watch, surface, onProgress });
     } finally {
       await stopManagedWebTarget(started);
       onStatus("Stopped the managed web runtime.");
@@ -1818,7 +2049,7 @@ export async function runExploreTarget({
 
   if (selectedPlatform === "android") {
     const appId = String(selected.runtime?.applicationId || "").trim();
-    if (!appId) return { error: `The Android target '${selected.name}' has no confirmed application id — confirm it and rerun \`tapp init\`, or pass --app-id.` };
+    if (!appId) return { error: `The Android target '${selected.name}' has no confirmed application id — confirm it and call \`tapp_init\` or rerun \`npx -y @aarwitz/tapp@latest init\`, or pass --app-id.` };
     const task = selected.build?.task || "assembleDebug";
     onStatus(`Building the Android APK (${task})…`);
     const built = await buildAndroidApp({
@@ -1856,6 +2087,22 @@ function openLocalPort() {
   });
 }
 
+function localPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.once("error", () => resolve(false));
+    server.listen(port, "127.0.0.1", () => server.close(() => resolve(true)));
+  });
+}
+
+export function managedWebDefaultPort(dependencies = {}) {
+  if (dependencies.vite) return 5173;
+  if (dependencies.next) return 3000;
+  if (dependencies["react-scripts"]) return 3000;
+  return 0;
+}
+
 function managedInstallSpec(command) {
   const known = {
     "npm ci": ["npm", ["ci"]],
@@ -1940,7 +2187,9 @@ export async function startManagedWebTarget({ root, requestedTarget = "", timeou
   const pkg = (() => { try { return JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8")); } catch { return {}; } })();
   const dependencies = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
   const declaredPort = startMatch ? declaredPortFromStartScript(pkg.scripts?.[startMatch[1]]) : 0;
-  const port = declaredPort || await openLocalPort();
+  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";
   let command = "npm";
   let startArgs;
   let startDir = projectDir;
@@ -1967,13 +2216,13 @@ export async function startManagedWebTarget({ root, requestedTarget = "", timeou
   const append = (chunk) => fs.appendFileSync(logPath, String(chunk));
   child.stdout.on("data", append);
   child.stderr.on("data", append);
-  onStatus(`Managed web runtime: ${command === process.execPath ? "Tapp static server" : `npm ${startArgs.join(" ")}`} → http://127.0.0.1:${port}`);
+  onStatus(`Managed web runtime: ${command === process.execPath ? "Tapp static server" : `npm ${startArgs.join(" ")}`} → http://127.0.0.1:${port} (${portBasis} port)`);
   const ready = await waitForOwnedUrl(`http://127.0.0.1:${port}`, child, Math.min(budgetMs, 60_000), logPath);
   if (ready.error) {
     await stopManagedWebTarget({ child, detached: process.platform !== "win32" });
     return ready;
   }
-  return { child, detached: process.platform !== "win32", url: `http://127.0.0.1:${port}`, logPath, install, build, start: { command, args: startArgs, cwd: startDir } };
+  return { child, detached: process.platform !== "win32", url: `http://127.0.0.1:${port}`, logPath, install, build, start: { command, args: startArgs, cwd: startDir, portBasis } };
 }
 
 export async function stopManagedWebTarget(runtime) {
@@ -2032,11 +2281,62 @@ const server = new Server(
   },
   {
     capabilities: {
+      prompts: {},
       tools: {},
     },
   }
 );
 
+const testAppPrompt = {
+  name: "test-app",
+  title: "Test this app with Tapp",
+  description: "Use Tapp's real app surfaces to inspect, drive, or explore this repository and report evidence honestly.",
+  arguments: [
+    {
+      name: "goal",
+      description: "What to verify, such as finding bugs or exercising checkout",
+      required: false,
+    },
+    {
+      name: "target",
+      description: "Optional repo target, bundle/app id, APK path, or owned URL",
+      required: false,
+    },
+  ],
+};
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [testAppPrompt] }));
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  if (request.params.name !== testAppPrompt.name) {
+    throw new Error(`Unknown prompt: ${request.params.name}`);
+  }
+  const goal = isNonEmptyString(request.params.arguments?.goal)
+    ? request.params.arguments.goal.trim()
+    : "Test the app and find important bugs";
+  const target = isNonEmptyString(request.params.arguments?.target)
+    ? ` Use this target: ${request.params.arguments.target.trim()}.`
+    : "";
+  return {
+    description: testAppPrompt.description,
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text:
+            `${goal}.${target} Use the connected Tapp tools on the real UI surface. ` +
+            "Use the smallest operation that satisfies the request; initialize/explore the source repo only for a general repository test. " +
+            "For a named screen/control, pass the exact request as session focus or call tapp_focus so Tapp uses source + its observed UI Map instead of wandering. " +
+            "If Tapp returns multiple target choices, ask me to select one instead of guessing. " +
+            "Read visual evidence before describing it. Report findings, coverage, authority, inconclusive state, and checked/not-checked scope; " +
+            "never turn exploration into a score or ship verdict. Do not edit the app unless I ask for a fix.",
+        },
+      },
+    ],
+  };
+});
+
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
@@ -2208,12 +2508,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           androidSerial: { type: "string", description: "Android: optional adb device serial; defaults to the first authorized device." },
           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." },
           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" },
           testPassword: { type: "string", description: "Password for the login preamble" },
           interactive: { type: "boolean", description: "Host-with-a-human only (e.g. the VS Code extension): pause at input screens and wait for values via interactiveResponsePath. Plain agents: omit." },
           interactiveResponsePath: { type: "string", description: "File path the prompting host answers on (requests appear at <path>.request)" },
+          visualReadyPath: { type: "string", description: "Local-client temp path written once the iOS target is foregrounded and settled, so previews exclude build/install footage" },
           inputOverrides: {
             type: "object",
             additionalProperties: { type: "string" },
@@ -2250,7 +2552,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
               "Findings from a previous run (pass back the `findings` array a prior tapp_explore returned). " +
               "When provided, the result adds a `regression` COMPARISON {counts:{new,persisting,resolved}, " +
               "newFindings, resolved} vs. that baseline — an observation, not a gate signal. To gate a merge, " +
-              "run `tapp ci` (or the GitHub Action): it applies the deterministic policy and returns the " +
+              "run `npx -y @aarwitz/tapp@latest ci` (or the GitHub Action): it applies the deterministic policy and returns the " +
               "pass/fail/inconclusive outcome.",
           },
         },
@@ -2278,6 +2580,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           timeout: { type: "integer", minimum: 30, maximum: 3600, default: 600 },
           testEmail: { type: "string", description: "Explore: actor/login email; never persisted in the model" },
           testPassword: { type: "string", description: "Explore: actor/login password; never persisted in the model" },
+          watch: { type: "boolean", default: false, description: "Web explore only: show the controlled browser and Tapp's actions" },
           maxContracts: { type: "integer", minimum: 1, maximum: 50, default: 15 },
           outDir: { type: "string", description: "Repo-relative artifact directory; default .tapp" },
         },
@@ -2661,10 +2964,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       name: "tapp_session_start",
       title: "Start interactive session",
       description:
-        "Start a PERSISTENT interactive session against an installed iOS or Android app. The app " +
+        "Start a PERSISTENT interactive session against an installed iOS/Android app or a web URL. The app " +
         "launches once and stays up, so you can drive a Playwright-style tap → inspect loop without a cold " +
         "launch per action. Returns the initial screen {screenTitle, elements[]}. Drive it with " +
-        "tapp_session_act and finish with tapp_session_end. Only one session at a time. Starts from a " +
+        "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. " +
         "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.",
@@ -2674,6 +2978,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           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)" },
           apkPath: { type: "string", description: "Android APK to install before starting" },
           androidSerial: { type: "string", description: "Android adb device serial" },
           clearData: { type: "boolean", default: true, description: "Android: clear app data before launch" },
@@ -2681,6 +2986,26 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           testPassword: { type: "string", description: "Password available to the app/harness" },
           appLaunchArgs: { type: "array", items: { type: "string" }, description: "Launch arguments, e.g. [\"--uitesting\"]" },
           appLaunchEnv: { type: "object", additionalProperties: { type: "string" }, description: "Launch environment, e.g. {\"UI_TEST_BACKEND\": \"staging\"}" },
+          focus: { type: "string", description: "Exact focused UI goal/control/screen to locate from repository source and reach through the shortest observed UI Map route before returning" },
+          projectDir: { type: "string", description: "Repository root for source-connected focus; defaults to the MCP workspace" },
+          mapPath: { type: "string", description: "Optional repository-relative UI Map for focus; defaults to .tapp/ui-map.json" },
+        },
+      },
+    },
+    {
+      name: "tapp_focus",
+      title: "Locate and reach a requested UI surface",
+      description:
+        "The FAST source-connected path for focused tasks. Locate a requested screen/control from owned repository source, reconcile it with Tapp's runtime-observed UI Map, and—when a session is active—execute the shortest replayable route in one call. Use before step-by-step tapping when the user names a destination such as 'Save storefront settings'. Source identifies intent; Tapp never invents navigation from source, and only observed/validated UI Map edges are executed. Without an active session this returns the grounded location/route plan without acting.",
+      inputSchema: {
+        type: "object",
+        required: ["query"],
+        properties: {
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
+          query: { type: "string", description: "User's requested screen, control, or focused UI task" },
+          projectDir: { type: "string", description: "Repository root; defaults to the MCP workspace" },
+          platform: { type: "string", enum: ["ios", "android", "web"], description: "Optional without an active session; an active session is authoritative" },
+          mapPath: { type: "string", description: "Optional repository-relative UI Map; defaults to .tapp/ui-map.json" },
         },
       },
     },
@@ -2731,45 +3056,62 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args = {} } = request.params;
 
   if (name === "tapp_health") {
-    const checks = [];
-
-    checks.push({
-      check: "repoRoot",
-      ok: fs.existsSync(path.join(repoRoot, "Tapp.xcodeproj")),
-      value: repoRoot,
+    const coreChecks = [];
+    coreChecks.push({
+      check: "workspace",
+      ok: fs.existsSync(workspaceRoot) && fs.statSync(workspaceRoot).isDirectory(),
+      value: workspaceRoot,
+      required: true,
     });
 
     const nodeVersion = await runCommand("node", ["-v"]);
-    checks.push({
+    coreChecks.push({
       check: "node",
       ok: nodeVersion.code === 0,
       value: nodeVersion.stdout.trim() || nodeVersion.stderr.trim(),
+      required: true,
     });
 
     const xcodebuildVersion = await runCommand("xcodebuild", ["-version"]);
-    checks.push({
-      check: "xcodebuild",
-      ok: xcodebuildVersion.code === 0,
-      value: (xcodebuildVersion.stdout || xcodebuildVersion.stderr).trim().split("\n")[0] || "not found",
-    });
-
-    const simctl = await runCommand("xcrun", ["simctl", "list", "devices", "booted"]);
-    checks.push({
-      check: "bootedSimulator",
-      ok: simctl.code === 0,
-      value: (simctl.stdout || simctl.stderr).trim(),
-    });
-
-    const allOk = checks.every((c) => c.ok);
+    const simctl = xcodebuildVersion.code === 0
+      ? await runCommand("xcrun", ["simctl", "list", "devices", "booted"])
+      : { code: 1, stdout: "", stderr: "Xcode not found" };
     const bootedLine = (simctl.stdout || "").split("\n").find((l) => /\(Booted\)/.test(l));
     const bootedName = bootedLine ? bootedLine.trim().replace(/\s*\(.*$/, "") : null;
-    const L = [`### ${allOk ? "🩺 Tapp ready" : "⚠️ Tapp not fully ready"}`, ""];
+    const adb = await runCommand("adb", ["devices"]);
+    const androidDevice = adb.code === 0
+      ? (adb.stdout || "").split("\n").find((line) => /\tdevice\s*$/.test(line))
+      : null;
+    let web = { ok: false, value: "Playwright or Chromium not installed" };
+    try {
+      const { chromium } = await import("playwright");
+      const executable = chromium.executablePath();
+      web = { ok: fs.existsSync(executable), value: fs.existsSync(executable) ? executable : "Chromium not installed" };
+    } catch { /* optional dependency may be intentionally absent */ }
+    const platformChecks = [
+      {
+        check: "iOS",
+        ok: xcodebuildVersion.code === 0 && !!bootedName,
+        value: bootedName ? `${bootedName} booted` : xcodebuildVersion.code === 0 ? "Xcode available; no simulator booted" : "Xcode not found",
+        required: false,
+      },
+      {
+        check: "Android",
+        ok: !!androidDevice,
+        value: androidDevice ? `${androidDevice.split("\t")[0]} connected` : adb.code === 0 ? "adb available; no authorized device" : "adb not found",
+        required: false,
+      },
+      { check: "web", ok: web.ok, value: web.value, required: false },
+    ];
+    const checks = [...coreChecks, ...platformChecks];
+    const ready = coreChecks.every((check) => check.ok) && platformChecks.some((check) => check.ok);
+    const L = [`### ${ready ? "🩺 Tapp ready" : "⚠️ Tapp needs a platform runtime"}`, ""];
     for (const c of checks) {
-      L.push(`- ${c.ok ? "✅" : "❌"} **${c.check}** — ${String(c.value).split("\n")[0] || "—"}`);
+      const icon = c.ok ? "✅" : c.required ? "❌" : "⚪️";
+      L.push(`- ${icon} **${c.check}** — ${String(c.value).split("\n")[0] || "—"}`);
     }
-    L.push("");
-    L.push(bootedName ? `📱 Simulator booted: **${bootedName}**` : "📱 No simulator booted — run `tapp_boot_simulator` first.");
-    return richResult(L.join("\n"), { ok: allOk, checks });
+    if (!ready) L.push("", "Run `npx -y @aarwitz/tapp@latest doctor` in the application repository for exact remediation.");
+    return richResult(L.join("\n"), { ok: ready, workspaceRoot, checks, platforms: Object.fromEntries(platformChecks.map((check) => [check.check.toLowerCase(), check.ok])) });
   }
 
   if (name === "tapp_build") {
@@ -2788,11 +3130,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (inst.error) return errorResult(inst.error);
       bundleId = inst.bundleId;
     }
+    let modelRefresh = null;
+    let modelRefreshWarning = "";
+    if (bundleId) {
+      try {
+        const { persistIosBuildValidation } = await import("./application-model.js");
+        modelRefresh = await persistIosBuildValidation({ projectDir: dir, bundleId, container: built.container, scheme: built.scheme, configuration: built.configuration });
+      } catch (error) {
+        modelRefreshWarning = error.message || String(error);
+      }
+    }
     const text =
       `🔨 Built **${path.basename(built.appPath)}** (scheme \`${built.scheme}\`) in ${fmtDuration(Date.now() - startedAt)}` +
       (bundleId ? ` — installed on the simulator as \`${bundleId}\`` : "") +
       `\n\nNext: \`tapp_explore\` with \`appBundleId: "${bundleId || "<install it first>"}"\`.`;
-    return richResult(text, { ok: true, appPath: built.appPath, scheme: built.scheme, container: built.container, bundleId });
+    return richResult(text + (modelRefresh ? `\nApplication model refreshed: \`${modelRefresh.modelPath}\`.` : modelRefreshWarning ? `\n⚠️ Application model refresh failed: ${modelRefreshWarning}` : ""), { ok: true, appPath: built.appPath, scheme: built.scheme, container: built.container, bundleId, modelRefreshed: !!modelRefresh, ...(modelRefreshWarning ? { modelRefreshWarning } : {}) });
   }
 
   if (name === "tapp_capture") {
@@ -2966,6 +3318,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (targets !== 1) {
       return errorResult("Provide exactly one of appBundleId (iOS), androidAppId (Android), or url (web beta)");
     }
+    if (args.watch === true && !wantsWeb) return errorResult("watch is currently available for web exploration only");
 
     // Both branches call the shared engine (runQaWeb/runQaIos) — the handler only adds
     // MCP concerns: auth, arg validation, and progress notifications.
@@ -2987,6 +3340,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         testEmail: args.testEmail,
         testPassword: args.testPassword,
         baselineFindings: args.baselineFindings,
+        watch: args.watch === true,
         onProgress: notifyProgress("pages reached"),
       });
       if (r.error) return errorResult(r.error, r.details || {});
@@ -3031,8 +3385,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = String(args.operation || "inspect").toLowerCase();
     if (!["inspect", "write", "refresh", "explore"].includes(operation)) return errorResult("operation must be inspect|write|refresh|explore");
-    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
-    if (!isInsideDir(repoRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the repo");
+    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(workspaceRoot, args.projectDir.trim()) : workspaceRoot;
+    if (!isInsideDir(workspaceRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the workspace");
     const maxContracts = asInteger(args.maxContracts, 15);
     if (maxContracts < 1 || maxContracts > 50) return errorResult("maxContracts must be between 1 and 50");
     const { initializeProductProject } = await import("./product-operations.js");
@@ -3042,32 +3396,42 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (!isInsideDir(projectDir, resolvedOut)) return errorResult("outDir must be inside projectDir");
       const selectedPlatform = isNonEmptyString(args.platform) ? args.platform.trim().toLowerCase()
         : isNonEmptyString(args.url) ? "web"
-        : isNonEmptyString(args.androidAppId) || isNonEmptyString(args.apkPath) ? "android" : "ios";
+        : isNonEmptyString(args.androidAppId) || isNonEmptyString(args.apkPath) ? "android" : "";
       const progressToken = request.params && request.params._meta ? request.params._meta.progressToken : undefined;
       const budget = Math.max(1, Math.min(1000, asInteger(args.maxActions, 40)));
       const result = await initializeProductProject({
         projectDir, mode: operation, outDir,
         ownedUrl: isNonEmptyString(args.url) ? args.url.trim() : "",
         platform: isNonEmptyString(args.platform) ? args.platform.trim().toLowerCase() : operation === "explore" ? selectedPlatform : "",
-        target: isNonEmptyString(args.target) ? args.target.trim() : projectDir,
+        target: isNonEmptyString(args.target) ? args.target.trim() : "",
         bundleId: isNonEmptyString(args.appBundleId) ? args.appBundleId.trim() : "",
         appId: isNonEmptyString(args.androidAppId) ? args.androidAppId.trim() : "",
         apkPath: isNonEmptyString(args.apkPath) ? path.resolve(projectDir, args.apkPath.trim()) : undefined,
         serial: isNonEmptyString(args.androidSerial) ? args.androidSerial.trim() : undefined,
         maxActions: args.maxActions, timeout: args.timeout, maxContracts,
         testEmail: args.testEmail, testPassword: args.testPassword,
+        watch: args.watch === true,
         runExploration: runInitExploration,
         onProgress: (progress) => {
           if (progressToken === undefined) return;
           server.notification({ method: "notifications/progress", params: { progressToken, progress: progress.action || 0, total: progress.max || budget, message: `Import exploration · ${progress.states} state(s) reached` } }).catch(() => {});
         },
       });
-      const { model, plan, written, exploration } = result;
-      const blocking = model.requirements.filter((item) => item.severity === "blocking");
+      const { model, plan, written, exploration, selectedTarget, requirementScope } = result;
+      const blocking = (requirementScope?.active || model.requirements).filter((item) => item.severity === "blocking");
+      const deferredBlocking = (requirementScope?.deferred || []).filter((item) => item.severity === "blocking");
       const pending = plan.items.filter((item) => item.decision === "pending");
-      const summary = `🧭 Tapp init — ${model.application.name} · ${model.targets.length} target(s) · UI Map ${model.uiMap.status} (${model.uiMap.nodeCount} states/${model.uiMap.edgeCount} transitions) · ${plan.items.length} plan item(s), ${pending.length} pending · ${blocking.length} blocking requirement(s)${exploration ? ` · real ${exploration.platform} exploration: ${(exploration.findings || []).length} finding(s)${exploration.inconclusive ? " (inconclusive)" : ""}` : ""}`;
-      return richResult(summary, { model, plan, written: written ? { modelPath: written.modelPath, planPath: written.planPath } : null, exploration });
-    } catch (error) { return errorResult("Could not initialize Tapp repository artifacts", { detail: error.message || String(error) }); }
+      const selectedLabel = selectedTarget ? ` for ${selectedTarget.platform}:${selectedTarget.name}` : "";
+      const deferredLabel = deferredBlocking.length ? ` · ${deferredBlocking.length} setup gap(s) on unselected target(s)` : "";
+      const summary = `🧭 Tapp init — ${model.application.name} · ${model.targets.length} target(s) · UI Map ${model.uiMap.status} (${model.uiMap.nodeCount} states/${model.uiMap.edgeCount} transitions) · ${plan.items.length} plan item(s), ${pending.length} pending · ${blocking.length} blocking requirement(s)${selectedLabel}${deferredLabel}${exploration ? ` · real ${exploration.platform} exploration: ${(exploration.findings || []).length} finding(s)${exploration.inconclusive ? " (inconclusive)" : ""}` : ""}`;
+      return richResult(summary, { model, plan, selectedTarget, requirementScope, written: written ? { modelPath: written.modelPath, planPath: written.planPath } : null, exploration });
+    } catch (error) {
+      const detail = error.message || String(error);
+      const message = error.details?.reason === "target-selection-required"
+        ? detail
+        : "Could not initialize Tapp repository artifacts";
+      return errorResult(message, { detail, ...(error.details || {}) });
+    }
   }
 
   if (name === "tapp_actor_config") {
@@ -3078,8 +3442,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const allowedArguments = new Set(["authToken", "operation", "projectDir", "name", "role", "session", "provisioning", "credentialBindings", "replace"]);
     const unexpectedArguments = Object.keys(args).filter((key) => !allowedArguments.has(key));
     if (unexpectedArguments.length) return errorResult("Unsupported actor configuration fields; credential values are never accepted", { fields: unexpectedArguments });
-    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
-    if (!isInsideDir(repoRoot, projectDir) || !fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) return errorResult("projectDir must be an existing directory inside the repo");
+    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(workspaceRoot, args.projectDir.trim()) : workspaceRoot;
+    if (!isInsideDir(workspaceRoot, projectDir) || !fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) return errorResult("projectDir must be an existing directory inside the workspace");
     const { configureActor, readProjectConfig } = await import("./project-config.js");
     if (operation === "read") {
       const loaded = readProjectConfig(projectDir);
@@ -3099,7 +3463,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         credentials,
         replace: asBoolean(args.replace),
       });
-      return richResult(`✅ Actor '${args.name.trim()}' configured with ${Object.keys(result.actor.credentials).length} environment binding(s); no credential values were accepted or written`, { path: result.path, actor: result.actor, next: "Run tapp_init refresh to update the application model and release plan." });
+      const { refreshExistingInitArtifacts } = await import("./application-model.js");
+      let refreshed = null;
+      let refreshWarning = "";
+      try { refreshed = await refreshExistingInitArtifacts({ projectDir }); }
+      catch (error) { refreshWarning = error.message || String(error); }
+      return richResult(
+        `✅ Actor '${args.name.trim()}' configured with ${Object.keys(result.actor.credentials).length} environment binding(s); no credential values were accepted or written${refreshed ? " · application model refreshed" : ""}${refreshWarning ? `\n⚠️ Application model refresh failed: ${refreshWarning}` : ""}`,
+        { path: result.path, actor: result.actor, modelRefreshed: !!refreshed, ...(refreshed ? { modelPath: refreshed.modelPath, planPath: refreshed.planPath } : {}), ...(refreshWarning ? { refreshWarning } : {}) },
+      );
     } catch (error) { return errorResult("Actor not configured", { detail: error.message || String(error) }); }
   }
 
@@ -3108,8 +3480,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = String(args.operation || "read").toLowerCase();
     if (!["read", "review", "generate", "validate", "promote"].includes(operation)) return errorResult("operation must be read|review|generate|validate|promote");
-    const planPath = isNonEmptyString(args.planPath) ? path.resolve(repoRoot, args.planPath.trim()) : existingProjectArtifactPath(repoRoot, "release-plan.json");
-    if (!isInsideDir(repoRoot, planPath)) return errorResult("planPath must be inside the repo");
+    const planPath = isNonEmptyString(args.planPath) ? path.resolve(workspaceRoot, args.planPath.trim()) : existingProjectArtifactPath(workspaceRoot, "release-plan.json");
+    if (!isInsideDir(workspaceRoot, planPath)) return errorResult("planPath must be inside the workspace");
     if (!fs.existsSync(planPath)) return errorResult("Release plan not found", { planPath });
     let plan;
     try { plan = JSON.parse(fs.readFileSync(planPath, "utf8")); }
@@ -3119,11 +3491,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (![...decisions.approve, ...decisions.reject, ...decisions.defer].length) return errorResult("review requires at least one approve, reject, or defer item");
       const { reviewProductPlan } = await import("./product-operations.js");
       try {
-        plan = reviewProductPlan({ projectDir: repoRoot, planPath, ...decisions }).plan;
+        plan = reviewProductPlan({ projectDir: workspaceRoot, planPath, ...decisions }).plan;
       } catch (error) { return errorResult("Could not review release plan", { detail: error.message || String(error) }); }
     } else if (operation === "generate") {
-      const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
-      if (!isInsideDir(repoRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the repo");
+      const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(workspaceRoot, args.projectDir.trim()) : workspaceRoot;
+      if (!isInsideDir(workspaceRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the workspace");
       const { generateProductPlan } = await import("./product-operations.js");
       try {
         const result = await generateProductPlan({ projectDir, planPath });
@@ -3131,8 +3503,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return richResult(`🧩 Proposal drafts — ${result.generatedTasks.length} UI-Map-grounded Task(s) · ${result.generated.length} compile-checked/untrusted contract(s) · ${result.blocked.length} blocked; deterministic real-surface replay remains required`, { plan, planPath, generatedTasks: result.generatedTasks, generated: result.generated, blocked: result.blocked });
       } catch (error) { return errorResult("Could not generate contract drafts", { detail: error.message || String(error) }); }
     } else if (operation === "validate") {
-      const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
-      if (!isInsideDir(repoRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the repo");
+      const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(workspaceRoot, args.projectDir.trim()) : workspaceRoot;
+      if (!isInsideDir(workspaceRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the workspace");
       let apkPath = "";
       if (isNonEmptyString(args.apkPath)) {
         apkPath = path.resolve(projectDir, args.apkPath.trim());
@@ -3164,8 +3536,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return richResult(`🔎 Generated contract validation passed — ${result.results.length}/${result.results.length} on ${result.platform}`, { ...result, planPath });
       } catch (error) { return errorResult("Generated contract validation failed", { detail: error.message || String(error), plan, planPath }); }
     } else if (operation === "promote") {
-      const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
-      if (!isInsideDir(repoRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the repo");
+      const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(workspaceRoot, args.projectDir.trim()) : workspaceRoot;
+      if (!isInsideDir(workspaceRoot, projectDir) || !fs.existsSync(projectDir)) return errorResult("projectDir must be an existing directory inside the workspace");
       const { promoteProductPlan } = await import("./product-operations.js");
       try {
         const result = await promoteProductPlan({ projectDir, planPath, items: Array.isArray(args.items) ? args.items : [] });
@@ -3181,9 +3553,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = String(args.operation || "inspect").toLowerCase();
     if (!["inspect", "install", "baseline"].includes(operation)) return errorResult("operation must be inspect|install|baseline");
-    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
-    if (!isInsideDir(repoRoot, projectDir) || !fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) return errorResult("projectDir must be an existing directory inside the repo");
-    const modelPath = isNonEmptyString(args.modelPath) ? path.resolve(repoRoot, args.modelPath.trim()) : existingProjectArtifactPath(projectDir, "application-model.json");
+    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(workspaceRoot, args.projectDir.trim()) : workspaceRoot;
+    if (!isInsideDir(workspaceRoot, projectDir) || !fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) return errorResult("projectDir must be an existing directory inside the workspace");
+    const modelPath = isNonEmptyString(args.modelPath) ? path.resolve(workspaceRoot, args.modelPath.trim()) : existingProjectArtifactPath(projectDir, "application-model.json");
     if (!isInsideDir(projectDir, modelPath) || !fs.existsSync(modelPath)) return errorResult("Application model not found inside projectDir; run tapp_init first", { modelPath });
     let model;
     try { model = JSON.parse(fs.readFileSync(modelPath, "utf8")); }
@@ -3191,8 +3563,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { createProductBaseline, installProductCi, prepareProductCi } = await import("./product-operations.js");
     if (operation === "baseline") {
       if (!isNonEmptyString(args.reportPath)) return errorResult("baseline requires reportPath from a successful portable gate");
-      const reportPath = path.resolve(repoRoot, args.reportPath.trim());
-      if (!isInsideDir(repoRoot, reportPath) || !fs.existsSync(reportPath)) return errorResult("reportPath must be an existing JSON file inside the repo");
+      const reportPath = path.resolve(workspaceRoot, args.reportPath.trim());
+      if (!isInsideDir(workspaceRoot, reportPath) || !fs.existsSync(reportPath)) return errorResult("reportPath must be an existing JSON file inside the workspace");
       let report;
       try { report = JSON.parse(fs.readFileSync(reportPath, "utf8")); }
       catch (error) { return errorResult("Gate report is invalid JSON", { detail: error.message || String(error) }); }
@@ -3217,8 +3589,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = String(args.operation || "read").toLowerCase();
     const resolveRepoFile = (value, fallback = "") => {
-      const resolved = path.resolve(repoRoot, isNonEmptyString(value) ? value.trim() : fallback);
-      return isInsideDir(repoRoot, resolved) ? resolved : null;
+      const resolved = path.resolve(workspaceRoot, isNonEmptyString(value) ? value.trim() : fallback);
+      return isInsideDir(workspaceRoot, resolved) ? resolved : null;
     };
     const capture = isNonEmptyString(args.captureId) ? listCaptureRuns(200).find((run) => run.id === args.captureId.trim()) : null;
     if (isNonEmptyString(args.captureId) && !capture) return errorResult("Capture not found", { captureId: args.captureId });
@@ -3238,18 +3610,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const markersPath = capture ? path.join(capture.path, "ocqa-markers.txt") : resolveRepoFile(args.markersPath);
       if (!markersPath) return errorResult("markersPath must be inside the repo, or provide captureId");
       if (!fs.existsSync(markersPath)) return errorResult("OCQA markers not found", { markersPath });
-      const outPath = isNonEmptyString(args.mapPath) ? resolveRepoFile(args.mapPath) : existingProjectArtifactPath(repoRoot, "ui-map.json");
+      const outPath = isNonEmptyString(args.mapPath) ? resolveRepoFile(args.mapPath) : existingProjectArtifactPath(workspaceRoot, "ui-map.json");
       if (!outPath) return errorResult("mapPath must be inside the repo");
       try {
         const observed = buildUiMapFromMarkers({ markersPath, platform: args.platform || "ios", target: args.target || "", runId: capture?.id || "" });
         const map = fs.existsSync(outPath) && args.replace !== true ? mergeUiMaps(JSON.parse(fs.readFileSync(outPath, "utf8")), observed) : observed;
         writeUiMap(outPath, map);
         const controls = map.nodes.reduce((total, node) => total + node.controls.length, 0);
-        return richResult(`🗺️ UI Map updated — ${map.nodes.length} states · ${map.edges.length} transitions · ${controls} semantic controls\n${path.relative(repoRoot, outPath)}`, { map, path: outPath });
+        return richResult(`🗺️ UI Map updated — ${map.nodes.length} states · ${map.edges.length} transitions · ${controls} semantic controls\n${path.relative(workspaceRoot, outPath)}`, { map, path: outPath });
       } catch (error) { return errorResult("Could not build UI Map", { detail: error.message || String(error) }); }
     }
     if (operation !== "read") return errorResult("operation must be read|build|diff");
-    const mapPath = capture ? path.join(capture.path, "ui-map.json") : isNonEmptyString(args.mapPath) ? resolveRepoFile(args.mapPath) : existingProjectArtifactPath(repoRoot, "ui-map.json");
+    const mapPath = capture ? path.join(capture.path, "ui-map.json") : isNonEmptyString(args.mapPath) ? resolveRepoFile(args.mapPath) : existingProjectArtifactPath(workspaceRoot, "ui-map.json");
     if (!mapPath) return errorResult("mapPath must be inside the repo");
     if (!fs.existsSync(mapPath)) return errorResult("UI Map not found; run QA or operation=build first", { mapPath });
     try {
@@ -3266,8 +3638,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = String(args.operation || "validate").toLowerCase();
     if (!["read", "validate", "compile"].includes(operation)) return errorResult("operation must be read|validate|compile");
-    const taskPath = isNonEmptyString(args.taskPath) ? path.resolve(repoRoot, args.taskPath.trim()) : null;
-    if (!taskPath || !isInsideDir(repoRoot, taskPath)) return errorResult("taskPath must be inside the repo");
+    const taskPath = isNonEmptyString(args.taskPath) ? path.resolve(workspaceRoot, args.taskPath.trim()) : null;
+    if (!taskPath || !isInsideDir(workspaceRoot, taskPath)) return errorResult("taskPath must be inside the workspace");
     if (!fs.existsSync(taskPath)) return errorResult("Task file not found", { taskPath: args.taskPath });
     const { applyTaskCoverage, compileTaskSteps, loadTaskFile, loadTaskRegistry, validateTaskAgainstUiMap } = await import("./task-runtime.js");
     let task;
@@ -3278,8 +3650,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     let groundingMap = null;
     let groundingMapPath = null;
     if (isNonEmptyString(args.mapPath)) {
-      const mapPath = path.resolve(repoRoot, args.mapPath.trim());
-      if (!isInsideDir(repoRoot, mapPath)) return errorResult("mapPath must be inside the repo");
+      const mapPath = path.resolve(workspaceRoot, args.mapPath.trim());
+      if (!isInsideDir(workspaceRoot, mapPath)) return errorResult("mapPath must be inside the workspace");
       if (!fs.existsSync(mapPath)) return errorResult("UI Map not found", { mapPath: args.mapPath });
       groundingMapPath = mapPath;
       try {
@@ -3309,12 +3681,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const flow = { name: `Task: ${task.name}`, kind: "flow", platform: args.platform || "", vars: compiled.vars, steps: compiled.steps, taskPlan: compiled.plan };
     let outPath = null;
     if (isNonEmptyString(args.outPath)) {
-      outPath = path.resolve(repoRoot, args.outPath.trim());
-      if (!isInsideDir(repoRoot, outPath)) return errorResult("outPath must be inside the repo");
+      outPath = path.resolve(workspaceRoot, args.outPath.trim());
+      if (!isInsideDir(workspaceRoot, outPath)) return errorResult("outPath must be inside the workspace");
       fs.mkdirSync(path.dirname(outPath), { recursive: true });
       fs.writeFileSync(outPath, JSON.stringify(flow, null, 2) + "\n");
     }
-    return richResult(`🧩 Compiled ${task.name} into ${flow.steps.length} deterministic Flow steps${outPath ? `\n${path.relative(repoRoot, outPath)}` : ""}`, { flow, grounding, path: outPath });
+    return richResult(`🧩 Compiled ${task.name} into ${flow.steps.length} deterministic Flow steps${outPath ? `\n${path.relative(workspaceRoot, outPath)}` : ""}`, { flow, grounding, path: outPath });
   }
 
   if (name === "tapp_release_contract") {
@@ -3322,8 +3694,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = String(args.operation || "validate").toLowerCase();
     if (!["read", "validate", "compile", "run"].includes(operation)) return errorResult("operation must be read|validate|compile|run");
-    const contractPath = isNonEmptyString(args.contractPath) ? path.resolve(repoRoot, args.contractPath.trim()) : null;
-    if (!contractPath || !isInsideDir(repoRoot, contractPath)) return errorResult("contractPath must be inside the repo");
+    const contractPath = isNonEmptyString(args.contractPath) ? path.resolve(workspaceRoot, args.contractPath.trim()) : null;
+    if (!contractPath || !isInsideDir(workspaceRoot, contractPath)) return errorResult("contractPath must be inside the workspace");
     const {
       applyReleaseContractCoverage,
       compileReleaseContract,
@@ -3338,8 +3710,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     let groundingMap = null;
     let groundingMapPath = null;
     if (isNonEmptyString(args.mapPath)) {
-      groundingMapPath = path.resolve(repoRoot, args.mapPath.trim());
-      if (!isInsideDir(repoRoot, groundingMapPath)) return errorResult("mapPath must be inside the repo");
+      groundingMapPath = path.resolve(workspaceRoot, args.mapPath.trim());
+      if (!isInsideDir(workspaceRoot, groundingMapPath)) return errorResult("mapPath must be inside the workspace");
       if (!fs.existsSync(groundingMapPath)) return errorResult("UI Map not found", { mapPath: args.mapPath });
       try {
         groundingMap = JSON.parse(fs.readFileSync(groundingMapPath, "utf8"));
@@ -3360,8 +3732,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     catch (error) { return errorResult("Could not compile Release Contract", { detail: error.message || String(error) }); }
     let outPath = null;
     if (isNonEmptyString(args.outPath)) {
-      outPath = path.resolve(repoRoot, args.outPath.trim());
-      if (!isInsideDir(repoRoot, outPath)) return errorResult("outPath must be inside the repo");
+      outPath = path.resolve(workspaceRoot, args.outPath.trim());
+      if (!isInsideDir(workspaceRoot, outPath)) return errorResult("outPath must be inside the workspace");
       fs.mkdirSync(path.dirname(outPath), { recursive: true });
       fs.writeFileSync(outPath, JSON.stringify(execution, null, 2) + "\n");
     }
@@ -3408,12 +3780,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = isNonEmptyString(args.operation) ? args.operation.trim().toLowerCase() : "plan";
     if (!['plan', 'adopt'].includes(operation)) return errorResult("operation must be plan|adopt");
-    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
-    if (!isInsideDir(repoRoot, projectDir)) return errorResult("projectDir must be inside the repo");
+    const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(workspaceRoot, args.projectDir.trim()) : workspaceRoot;
+    if (!isInsideDir(workspaceRoot, projectDir)) return errorResult("projectDir must be inside the workspace");
     if (operation === "adopt") {
       if (!isNonEmptyString(args.prPlanPath) || !isNonEmptyString(args.item)) return errorResult("adopt requires prPlanPath and item");
       const prPlanPath = path.resolve(projectDir, args.prPlanPath.trim());
-      if (!isInsideDir(repoRoot, prPlanPath)) return errorResult("prPlanPath must be inside the repo");
+      if (!isInsideDir(workspaceRoot, prPlanPath)) return errorResult("prPlanPath must be inside the workspace");
       const { adoptPrCoverageProposal } = await import("./pr-selection.js");
       try {
         const adopted = adoptPrCoverageProposal({
@@ -3457,8 +3829,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       fs.writeFileSync(flowFile, JSON.stringify(args.flow));
       parsedFlow = args.flow;
     } else if (isNonEmptyString(args.flowPath)) {
-      const p = path.resolve(repoRoot, args.flowPath.trim());
-      if (!isInsideDir(repoRoot, p)) return errorResult("flowPath must be inside the repo");
+      const p = path.resolve(workspaceRoot, args.flowPath.trim());
+      if (!isInsideDir(workspaceRoot, p)) return errorResult("flowPath must be inside the workspace");
       if (!fs.existsSync(p)) return errorResult("Flow file not found", { flowPath: args.flowPath });
       flowFile = p;
     } else {
@@ -3477,15 +3849,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         (args.url || parsedFlow.url || /^https?:\/\//i.test(parsedFlow.app || "")) ? "web" : "ios")
     ).toLowerCase();
 
-    const flowLog = path.join(os.tmpdir(), `mcp-flow-${Date.now()}.log`);
-    const runEnv = { ...process.env, FLOW_LOG: flowLog };
+    const flowToken = Date.now();
+    const flowLog = path.join(os.tmpdir(), `mcp-flow-${flowToken}.log`);
+    const evidenceDir = path.join(capturesDir, `flow-${platform}-${flowToken}`);
+    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();
     let run = { stdout: "", stderr: "", code: 0 };
     if (platform === "web") {
       try {
         const { runWebFlow } = await import("./web-flow.js");
-        const evidenceDir = path.join(capturesDir, `flow-web-${Date.now()}`);
         const result = await runWebFlow({
           flow: parsedFlow,
           url: isNonEmptyString(args.url) ? args.url.trim() : undefined,
@@ -3500,10 +3873,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const cmdArgs = [path.join(scriptsDir, "run-flow.sh"), flowFile];
       if (isNonEmptyString(args.appBundleId)) cmdArgs.push(args.appBundleId.trim());
       run = await runCommand("bash", cmdArgs, { cwd: repoRoot, timeoutMs: 10 * 60 * 1000, env: runEnv });
+      if (fs.existsSync(evidenceDir) && fs.readdirSync(evidenceDir).length > 0) run.evidenceDir = evidenceDir;
     } else if (platform === "android") {
       try {
         const { runAndroidFlow } = await import("./android-flow.js");
-        const evidenceDir = path.join(capturesDir, `flow-android-${Date.now()}`);
         const result = await runAndroidFlow({
           flow: parsedFlow,
           appId: isNonEmptyString(args.androidAppId)
@@ -3530,7 +3903,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try { structured = JSON.parse(jsonRes.stdout.trim()); } catch { /* fall through */ }
     const textRes = await runCommand("python3", [path.join(scriptsDir, "flow_lib.py"), "report", flowLog], { cwd: repoRoot });
     const text = (textRes.stdout || "").trim() || run.stdout;
-    return richResult(text, { ...(structured || { raw: run.stdout }), platform, evidenceDir: run.evidenceDir });
+    const retainedEvidence = run.evidenceDir && fs.existsSync(run.evidenceDir) && fs.readdirSync(run.evidenceDir).length > 0
+      ? run.evidenceDir
+      : undefined;
+    const evidenceText = retainedEvidence
+      ? `\n\nEvidence: \`${retainedEvidence}\``
+      : "\n\n⚠️ Evidence unavailable — the platform runner did not write any artifacts for this Flow run.";
+    return richResult(text + evidenceText, { ...(structured || { raw: run.stdout }), platform, ...(retainedEvidence ? { evidenceDir: retainedEvidence } : {}) });
   }
 
   if (name === "tapp_scenario_run") {
@@ -3540,8 +3919,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (args.scenario && typeof args.scenario === "object") {
       scenario = args.scenario;
     } else if (isNonEmptyString(args.scenarioPath)) {
-      const scenarioFile = path.resolve(repoRoot, args.scenarioPath.trim());
-      if (!isInsideDir(repoRoot, scenarioFile)) return errorResult("scenarioPath must be inside the repo");
+      const scenarioFile = path.resolve(workspaceRoot, args.scenarioPath.trim());
+      if (!isInsideDir(workspaceRoot, scenarioFile)) return errorResult("scenarioPath must be inside the workspace");
       if (!fs.existsSync(scenarioFile)) return errorResult("Scenario file not found", { scenarioPath: args.scenarioPath });
       try {
         const { loadScenarioFile } = await import("./scenario-runtime.js");
@@ -3611,7 +3990,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const ungrounded = ungroundedScreens(parsed.steps, grounding);
     const flow = { name: args.name || parsed.name, app: bundleId, steps: parsed.steps };
     const slug = flow.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "generated-flow";
-    const dir = path.join(repoRoot, ".tapp", "proposals", "flows");
+    const dir = path.join(workspaceRoot, ".tapp", "proposals", "flows");
     fs.mkdirSync(dir, { recursive: true });
     const outPath = path.join(dir, `${slug}.yml`);
     const promotedPath = path.join(".tapp", "flows", `${slug}.yml`);
@@ -3619,7 +3998,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const yaml = (yamlRes.stdout || "").trim();
     if (!yaml) return errorResult("Failed to render flow YAML", { stderr: yamlRes.stderr });
     fs.writeFileSync(outPath, yaml + "\n");
-    const rel = path.relative(repoRoot, outPath);
+    const rel = path.relative(workspaceRoot, outPath);
 
     const L = [`🤖 Generated a flow **proposal** **${flow.name}** from your goal → \`${rel}\``];
     L.push(`⚠️ This is an **untrusted draft**, not a committed test. Grounded in ${grounding.screens.length} observed screen(s). ${ungrounded.length ? `⚠️ references unobserved: ${ungrounded.join(", ")} — review before relying on it.` : "All referenced screens were observed."}`);
@@ -3821,17 +4200,66 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const ios = isNonEmptyString(args.appBundleId);
     const android = isNonEmptyString(args.androidAppId);
-    if (ios === android) return errorResult("Provide exactly one of appBundleId or androidAppId");
-    const target = ios ? args.appBundleId.trim() : args.androidAppId.trim();
+    const web = isNonEmptyString(args.url);
+    if ([ios, android, web].filter(Boolean).length !== 1) return errorResult("Provide exactly one of appBundleId, androidAppId, or url");
+    const target = ios ? args.appBundleId.trim() : android ? args.androidAppId.trim() : args.url.trim();
+    let focusProjectDir = workspaceRoot;
+    if (isNonEmptyString(args.focus)) {
+      try { focusProjectDir = fs.realpathSync(path.resolve(workspaceRoot, isNonEmptyString(args.projectDir) ? args.projectDir.trim() : ".")); }
+      catch { return errorResult("projectDir must be an existing directory inside the workspace"); }
+      if (!isInsideDir(workspaceRoot, focusProjectDir) || !fs.statSync(focusProjectDir).isDirectory()) return errorResult("projectDir must be an existing directory inside the workspace");
+    }
     const r = ios
       ? await startSession(target, explorationEnvFromArgs(args))
-      : await startAndroidSession(target, { serial: args.androidSerial, apkPath: args.apkPath, clearData: args.clearData !== false, testEmail: args.testEmail, testPassword: args.testPassword });
+      : android
+        ? await startAndroidSession(target, { serial: args.androidSerial, apkPath: args.apkPath, clearData: args.clearData !== false, testEmail: args.testEmail, testPassword: args.testPassword })
+        : await startWebSession(target, { testEmail:args.testEmail, testPassword:args.testPassword });
     if (r.error) return errorResult(r.error);
-    return richResult(
-      `🎬 Session started — \`${target}\` (${ios ? "iOS" : "Android"})\n\n` + formatScreen(r.screenTitle, r.elements) +
-        `\n\nDrive it with \`tapp_session_act\` (tap · type · swipe · back · wait · tree · screenshot).`,
-      r
-    );
+    let focused = null;
+    if (isNonEmptyString(args.focus)) {
+      try {
+        focused = await focusInteractiveSession({ projectDir:focusProjectDir, query:args.focus.trim(), platform:ios ? "ios" : android ? "android" : "web", mapPath:isNonEmptyString(args.mapPath) ? args.mapPath.trim() : "" });
+      } catch (error) {
+        await endSession();
+        return errorResult("Could not focus the requested UI surface", { detail:error.message || String(error) });
+      }
+    }
+    const platformLabel = ios ? "iOS" : android ? "Android" : "web";
+    const screen = agentScreenProjection(focused || r);
+    const text = focused
+      ? `🎬 Session started — \`${target}\` (${platformLabel})\n\n${(await import("./focused-navigation.js")).focusedTargetSummary(focused)}\n\n${formatScreen(screen.screenTitle, screen.elements)}`
+      : `🎬 Session started — \`${target}\` (${platformLabel})\n\n${formatScreen(screen.screenTitle, screen.elements)}\n\nDrive it with \`tapp_focus\` for a named destination, or \`tapp_session_act\` for one action.`;
+    // Return the final focused screen once. Previously this duplicated the complete native tree
+    // inside `focus` and at top level, and retained the pre-focus web URL at top level.
+    const structured = focused
+      ? { ok:true, platform:ios ? "ios" : android ? "android" : "web", ...screen, focus:focusMetadata(focused) }
+      : { ...r, ...screen };
+    const result = richResult(text, structured);
+    if (focused?.execution?.status === "failed") result.isError = true;
+    return result;
+  }
+
+  if (name === "tapp_focus") {
+    const unauthorized = ensureAuthorized(args);
+    if (unauthorized) return unauthorized;
+    if (!isNonEmptyString(args.query)) return errorResult("query is required");
+    let projectDir;
+    try { projectDir = fs.realpathSync(path.resolve(workspaceRoot, isNonEmptyString(args.projectDir) ? args.projectDir.trim() : ".")); }
+    catch { return errorResult("projectDir must be an existing directory inside the workspace"); }
+    if (!isInsideDir(workspaceRoot, projectDir) || !fs.statSync(projectDir).isDirectory()) return errorResult("projectDir must be an existing directory inside the workspace");
+    try {
+      const result = await focusInteractiveSession({
+        projectDir, query:args.query.trim(), platform:isNonEmptyString(args.platform) ? args.platform.trim() : "",
+        mapPath:isNonEmptyString(args.mapPath) ? args.mapPath.trim() : "",
+      });
+      const { focusedTargetSummary } = await import("./focused-navigation.js");
+      const execution = result.execution?.status === "reached"
+        ? `\n\n⚡ Reached in ${(result.execution.steps || []).length} route action(s).\n\n${formatScreen(result.screenTitle, agentFacingElements(result.elements))}`
+        : result.execution?.status === "failed" ? `\n\n⚠️ Route execution stopped: ${result.execution.reason}` : "";
+      const response = richResult(focusedTargetSummary(result) + execution, { ...result, ...agentScreenProjection(result) });
+      if (result.execution?.status === "failed") response.isError = true;
+      return response;
+    } catch (error) { return errorResult("Could not focus the requested UI surface", { detail:error.message || String(error) }); }
   }
 
   if (name === "tapp_session_act") {
@@ -3867,14 +4295,17 @@ 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.` : "";
-    return richResult(head + "\n\n" + formatScreen(r.screenTitle, r.elements) + rec, r);
+    const screen = agentScreenProjection(r);
+    const result = richResult(head + "\n\n" + formatScreen(screen.screenTitle, screen.elements) + rec, { ...r, ...screen });
+    if (!ok) result.isError = true;
+    return result;
   }
 
   if (name === "tapp_flow_save") {
     const unauthorized = ensureAuthorized(args);
     if (unauthorized) return unauthorized;
     try {
-      const saved = await saveInteractiveSessionFlow({ projectDir:repoRoot, name:args.name, addFinalAssertion:args.addFinalAssertion !== false, replace:args.replace === true });
+      const saved = await saveInteractiveSessionFlow({ projectDir:workspaceRoot, name:args.name, addFinalAssertion:args.addFinalAssertion !== false, replace:args.replace === true });
       const text = `💾 Saved flow **${saved.flow.name}** → \`${saved.path}\` (${saved.flow.steps.length} steps)\n\n\`\`\`yaml\n${saved.yaml}\n\`\`\`\n\nReplay it anytime: \`tapp_flow_run\` with \`flowPath: "${saved.path}"\`.`;
       return richResult(text, { path:saved.path, flow:saved.flow });
     } catch (error) {