@aarwitz/tapp 0.17.0-rc.9 → 0.17.1

package/bin/tapp.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// tapp CLI — ship with proof.
+// Tapp CLI — agent-driven app testing on real app surfaces.
 //
 //   Zero-config verbs (the same engine the MCP tools use, exported by mcp-server/src/index.js):
 //   tapp explore <bundleId|appId|url> Autonomous exploration → findings + evidence (observation)
@@ -28,8 +28,8 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, "..");
 const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
 
-// Redirect all writable output away from the (possibly read-only) package dir.
-// The old environment alias remains a read-only fallback for older integrations.
+// Redirect all writable output away from the (possibly read-only) package dir. TAPP_HOME and
+// ~/.tapp are the only current runtime locations; retired environment/path aliases are ignored.
 const tappHome = (process.env.TAPP_HOME || path.join(os.homedir(), ".tapp")).trim();
 process.env.TAPP_HOME = tappHome;
 // TAPP_HOME is created lazily (just before the switch) so `--help`, `help`, and `version` never
@@ -53,6 +53,19 @@ function bad(label, detail = "") {
   console.log(`  ❌ ${label}${detail ? ` — ${detail}` : ""}`);
 }
 
+let lastProgressLine = "";
+function writeProgress(line) {
+  const text = String(line || "").trimEnd();
+  if (process.stderr.isTTY) process.stderr.write(`\r${text}   `);
+  else if (text && text !== lastProgressLine) console.error(text);
+  lastProgressLine = text;
+}
+
+function finishProgress() {
+  if (process.stderr.isTTY && lastProgressLine) process.stderr.write("\n");
+  lastProgressLine = "";
+}
+
 function bootedSims() {
   const r = run("xcrun", ["simctl", "list", "devices", "booted", "-j"]);
   if (r.code !== 0) return [];
@@ -155,7 +168,7 @@ const engineImport = () => import(path.join(packageRoot, "mcp-server", "src", "i
 
 function requireMacFor(what) {
   if (process.platform === "darwin") return;
-  console.error(`❌ ${what} requires macOS (Xcode + iOS simulator). The web beta runs anywhere: tapp explore https://localhost:3000`);
+  console.error(`❌ ${what} requires macOS (Xcode + iOS simulator). The web beta runs anywhere: npx -y @aarwitz/tapp@latest explore https://localhost:3000`);
   process.exit(1);
 }
 
@@ -206,6 +219,26 @@ function printEngineError(r) {
   }
 }
 
+async function promptForInitTarget(details) {
+  const choices = Array.isArray(details?.choices) ? details.choices : [];
+  if (!choices.length || !process.stdin.isTTY || !process.stderr.isTTY || process.env.CI) return null;
+  const { createInterface } = await import("node:readline/promises");
+  const terminal = createInterface({ input: process.stdin, output: process.stderr });
+  console.error("\nTapp found multiple application targets. Which one should it explore?");
+  choices.forEach((choice, index) => console.error(`  ${index + 1}) ${choice.platform} · ${choice.name} (${choice.sourcePath})`));
+  try {
+    while (true) {
+      const answer = String(await terminal.question(`Select 1-${choices.length} (or q to cancel): `)).trim();
+      if (/^(?:q|quit|cancel)$/i.test(answer)) return null;
+      const selected = Number(answer);
+      if (Number.isInteger(selected) && selected >= 1 && selected <= choices.length) return choices[selected - 1];
+      console.error(`Enter a number from 1 to ${choices.length}, or q to cancel.`);
+    }
+  } finally {
+    terminal.close();
+  }
+}
+
 // Turn whatever the user gave us (nothing / repo dir / .app / bundle id) into an installed
 // bundle id, narrating build/install progress on stderr.
 async function resolveTargetOrExit(engine, input) {
@@ -220,14 +253,15 @@ async function resolveTargetOrExit(engine, input) {
 
 function safeCommandUsage(verb) {
   const usage = {
-    explore: "tapp explore [target] [--platform ios|android|web] [--actions N] [--timeout SEC] [--email VALUE] [--password VALUE] [--baseline FILE] [--json FILE]\n  iOS launch configuration: [--launch-arg VALUE ...] [--launch-env '{\"KEY\":\"VALUE\"}']\n  Android: [--app-id ID] [--apk FILE] [--serial ID] [--keep-data]",
-    init: "tapp init [repo] [--explore] [--refresh] [--platform PLATFORM] [--target NAME] [--url URL] [--dry-run]",
+    explore: "tapp explore [target] [--platform ios|android|web] [--actions N] [--timeout SEC] [--email VALUE] [--password VALUE] [--baseline FILE] [--json FILE]\n  Web: [--watch] opens Tapp's controlled browser and shows its actions\n  iOS launch configuration: [--launch-arg VALUE ...] [--launch-env '{\"KEY\":\"VALUE\"}']\n  Android: [--app-id ID] [--apk FILE] [--serial ID] [--keep-data]",
+    focus: "tapp focus \"SCREEN OR CONTROL\" [target] [--platform ios|android|web] [--project-dir REPO] [--map FILE] [--out FILE]",
+    init: "tapp init [repo] [--explore] [--refresh] [--platform PLATFORM] [--target NAME] [--url URL] [--watch] [--dry-run]",
     open: "tapp open [target] [--platform ios|android|web] [--out FILE] [--tap TEXT] [--wait-for TEXT]",
     tree: "tapp tree [target] [--platform ios|android|web] [--json] [--tap TEXT] [--wait-for TEXT]",
     shot: "tapp shot [--out FILE]",
     apps: "tapp apps",
     build: "tapp build [repo] [--scheme NAME] [--configuration NAME]",
-    flow: "tapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--email VALUE] [--password VALUE]",
+    flow: "tapp flow example\ntapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--email VALUE] [--password VALUE]",
     task: "tapp task validate FILE [--platform PLATFORM] [--map FILE]\ntapp task compile FILE --platform PLATFORM [--inputs JSON] [--out FILE]\ntapp task run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID] [--inputs JSON]",
     contract: "tapp contract validate FILE [--platform PLATFORM] [--map FILE]\ntapp contract compile FILE --platform PLATFORM [--out FILE]\ntapp contract run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID]",
     scenario: "tapp scenario validate FILE [--project-dir DIR]\ntapp scenario run FILE --platform web --url URL [--project-dir DIR]",
@@ -255,13 +289,22 @@ if (["--help", "-h"].includes(command)) {
   command = "help";
   rest = [];
 }
+const knownCommands = new Set([
+  "help", "version", "--version", "-v", "mcp", "init", "focus", "explore", "qa", "open",
+  "tree", "shot", "screenshot", "apps", "build", "flow", "task", "contract", "scenario", "map",
+  "pr", "plan", "baseline", "ci", "actor", "app", "studio", "report", "doctor", "install",
+]);
+if (!knownCommands.has(command)) {
+  console.error(`❌ Unknown command: ${command}`);
+  console.error("Run `npx -y @aarwitz/tapp@latest --help` for the command reference.");
+  process.exit(2);
+}
 const safeHelpRequested = (rest.includes("--help") || rest.includes("-h"))
   && !["help", "version", "--version", "-v"].includes(command)
   && (command !== "ci" || rest[0] === "install");
 if (safeHelpRequested) {
-  console.log(`Usage:\n  ${safeCommandUsage(command).replaceAll("\n", "\n  ")}\n\nℹ️  --help never builds, launches, writes, or opens. Full command reference:\n`);
-  command = "help";
-  rest = [];
+  console.log(`Usage:\n  ${safeCommandUsage(command).replaceAll("\n", "\n  ")}\n\nℹ️  --help never builds, launches, writes, or opens. Run \`tapp --help\` for the full command reference.`);
+  process.exit(0);
 }
 
 // Create TAPP_HOME only for commands that actually use it — never for help/version/--help.
@@ -302,7 +345,7 @@ switch (command) {
     }
     const platform = typeof flags.platform === "string" ? flags.platform.toLowerCase()
       : typeof flags.url === "string" ? "web"
-      : typeof flags["app-id"] === "string" || typeof flags.apk === "string" ? "android" : "ios";
+      : typeof flags["app-id"] === "string" || typeof flags.apk === "string" ? "android" : "";
     if (explore && platform === "ios") requireMacFor("iOS init exploration");
     const actions = flags.actions === undefined ? 40 : Number(flags.actions);
     const timeout = flags.timeout === undefined ? 600 : Number(flags.timeout);
@@ -312,51 +355,85 @@ switch (command) {
     }
     const engine = explore ? await engineImport() : null;
     const { initializeProductProject } = await import(path.join(packageRoot, "mcp-server", "src", "product-operations.js"));
+    const initOptions = {
+      projectDir,
+      mode: flags["dry-run"] === true ? "inspect" : explore ? "explore" : flags.refresh === true ? "refresh" : "write",
+      ownedUrl: typeof flags.url === "string" ? flags.url : "",
+      platform: typeof flags.platform === "string" ? flags.platform.toLowerCase() : explore ? platform : "",
+      target: typeof flags.target === "string" ? flags.target : "",
+      bundleId: typeof flags["bundle-id"] === "string" ? flags["bundle-id"] : "",
+      appId: typeof flags["app-id"] === "string" ? flags["app-id"] : "",
+      apkPath: typeof flags.apk === "string" ? path.resolve(flags.apk) : undefined,
+      serial: typeof flags.serial === "string" ? flags.serial : undefined,
+      maxActions: actions,
+      timeout,
+      testEmail: typeof flags.email === "string" ? flags.email : undefined,
+      testPassword: typeof flags.password === "string" ? flags.password : undefined,
+      watch: flags.watch === true,
+      runExploration: engine?.runInitExploration,
+      onProgress: (progress) => {
+        const activePlatform = progress.platform || platform;
+        writeProgress(`🔍 Import exploration… ${progress.action}/${progress.max || actions} actions · ${progress.states} ${activePlatform === "web" ? "pages reached" : activePlatform === "ios" ? "structural states observed" : "screens reached"}`);
+      },
+      onStatus: (status) => console.error(`⏳ ${status}`),
+      outDir,
+      maxContracts,
+    };
     let result;
+    let failure = null;
     try {
-      result = await initializeProductProject({
-        projectDir,
-        mode: flags["dry-run"] === true ? "inspect" : explore ? "explore" : flags.refresh === true ? "refresh" : "write",
-        ownedUrl: typeof flags.url === "string" ? flags.url : "",
-        platform: typeof flags.platform === "string" ? flags.platform.toLowerCase() : explore ? platform : "",
-        target: typeof flags.target === "string" ? flags.target : projectDir,
-        bundleId: typeof flags["bundle-id"] === "string" ? flags["bundle-id"] : "",
-        appId: typeof flags["app-id"] === "string" ? flags["app-id"] : "",
-        apkPath: typeof flags.apk === "string" ? path.resolve(flags.apk) : undefined,
-        serial: typeof flags.serial === "string" ? flags.serial : undefined,
-        maxActions: actions,
-        timeout,
-        testEmail: typeof flags.email === "string" ? flags.email : undefined,
-        testPassword: typeof flags.password === "string" ? flags.password : undefined,
-        runExploration: engine?.runInitExploration,
-        onProgress: (progress) => process.stderr.write(`\r🔍 Import exploration… ${progress.action}/${progress.max || actions} actions · ${progress.states} ${platform === "web" ? "pages reached" : platform === "ios" ? "structural states observed" : "screens reached"}   `),
-        onStatus: (status) => console.error(`⏳ ${status}`),
-        outDir,
-        maxContracts,
-      });
+      result = await initializeProductProject(initOptions);
     } catch (error) {
-      if (explore) process.stderr.write("\n");
-      console.error(`❌ Could not initialize repository: ${error.message || String(error)}`);
+      failure = error;
+      const choice = explore && error.details?.reason === "target-selection-required"
+        ? await promptForInitTarget(error.details)
+        : null;
+      if (choice) {
+        if (choice.platform === "ios") requireMacFor("iOS init exploration");
+        console.error(`🎯 Exploring ${choice.platform}:${choice.name} (${choice.sourcePath})`);
+        try {
+          result = await initializeProductProject({ ...initOptions, platform: choice.platform, target: choice.selector });
+          failure = null;
+        } catch (retryError) {
+          failure = retryError;
+        }
+      }
+    }
+    if (failure) {
+      if (explore) finishProgress();
+      printEngineError({ error: `Could not initialize repository: ${failure.message || String(failure)}`, details: failure.details || {} });
       process.exit(2);
     }
-    if (explore) process.stderr.write("\n");
+    if (explore) finishProgress();
     const built = { model: result.model, plan: result.plan };
     const written = result.written;
     const exploration = result.exploration;
     if (typeof flags["json-out"] === "string") {
       const out = path.resolve(flags["json-out"]);
       fs.mkdirSync(path.dirname(out), { recursive: true });
-      fs.writeFileSync(out, JSON.stringify({ model: built.model, plan: written?.plan || built.plan, ...(exploration ? { exploration } : {}) }, null, 2) + "\n");
-    }
-    const blocking = built.model.requirements.filter((item) => item.severity === "blocking");
+      fs.writeFileSync(out, JSON.stringify({
+        model: built.model,
+        plan: written?.plan || built.plan,
+        ...(exploration ? { exploration } : {}),
+        ...(result.selectedTarget ? { selectedTarget: result.selectedTarget } : {}),
+        requirementScope: result.requirementScope,
+      }, null, 2) + "\n");
+    }
+    const activeRequirements = result.requirementScope?.active || built.model.requirements;
+    const deferredRequirements = result.requirementScope?.deferred || [];
+    const blocking = activeRequirements.filter((item) => item.severity === "blocking");
+    const deferredBlocking = deferredRequirements.filter((item) => item.severity === "blocking");
     const pending = (written?.plan || built.plan).items.filter((item) => item.decision === "pending");
     console.log(`🧭 Tapp init — ${built.model.application.name}`);
     console.log(`   targets: ${built.model.targets.length ? built.model.targets.map((target) => `${target.platform}:${target.name}`).join(", ") : "none"}`);
     console.log(`   UI Map: ${built.model.uiMap.status} · ${built.model.uiMap.nodeCount} states · ${built.model.uiMap.edgeCount} transitions`);
     if (exploration) console.log(`   Exploration: ${(exploration.findings || []).length} finding(s)${exploration.inconclusive ? " (inconclusive)" : ""} · ${exploration.uiMap.nodeCount} states · evidence: ${exploration.reportHtml || exploration.capture?.path || "capture recorded"}`);
     if (exploration?.managedRuntime) console.log(`   Managed web runtime: built/started ${exploration.target} for exploration and stopped it afterward · log: ${exploration.runtime.logPath}`);
-    console.log(`   release plan: ${(written?.plan || built.plan).items.length} item(s) · ${pending.length} pending review · ${blocking.length} blocking requirement(s)`);
-    for (const requirement of built.model.requirements) console.log(`   ${requirement.severity === "blocking" ? "❌" : "⚠️"} ${requirement.message} Next: ${requirement.remediation}`);
+    const selectedLabel = result.selectedTarget ? ` for ${result.selectedTarget.platform}:${result.selectedTarget.name}` : "";
+    const deferredLabel = deferredBlocking.length ? ` · ${deferredBlocking.length} setup gap(s) on unselected target(s)` : "";
+    console.log(`   release plan: ${(written?.plan || built.plan).items.length} item(s) · ${pending.length} pending review · ${blocking.length} blocking requirement(s)${selectedLabel}${deferredLabel}`);
+    for (const requirement of activeRequirements) console.log(`   ${requirement.severity === "blocking" ? "❌" : "⚠️"} ${requirement.message} Next: ${requirement.remediation}`);
+    for (const requirement of deferredRequirements) console.log(`   ℹ️ Unselected ${requirement.targetPlatform}:${requirement.targetName} setup gap: ${requirement.message} Next: ${requirement.remediation}`);
     if (written) console.log(`   model: ${written.modelPath}\n   plan: ${written.planPath}`);
     else console.log("   dry run: repository files were not changed");
     break;
@@ -411,7 +488,10 @@ switch (command) {
           testPassword: typeof flags.password === "string" ? flags.password : undefined,
           startWebTarget: engine.startManagedWebTarget,
           stopWebTarget: engine.stopManagedWebTarget,
-          onProgress: (entry) => { if (entry.text) console.error(`⏳ ${entry.text}`); },
+          // Contract execution is emitted in full on stdout below. Keep build/runtime/replay
+          // status live on stderr, but do not echo the execution transcript there as well — an
+          // interactive terminal merges the streams and would otherwise show every result twice.
+          onProgress: (entry) => { if (entry.text && entry.phase !== "execute") console.error(`⏳ ${entry.text}`); },
         });
       } catch (error) {
         console.error(`❌ Could not validate contract drafts: ${error.message || String(error)}`);
@@ -460,6 +540,63 @@ switch (command) {
   // ---- Zero-config verbs: the same engine the MCP tools use (exported by index.js),
   // invokable by any agent or human with no server setup at all.
 
+  case "focus": {
+    const { flags, positionals } = parseVerbArgs(rest);
+    const query = positionals[0] || "";
+    if (!query) {
+      console.error('usage: tapp focus "SCREEN OR CONTROL" [target] [--platform ios|android|web] [--project-dir REPO] [--map FILE] [--out FILE]');
+      process.exit(2);
+    }
+    let projectDir;
+    try { projectDir = fs.realpathSync(path.resolve(typeof flags["project-dir"] === "string" ? flags["project-dir"] : process.cwd())); }
+    catch { console.error("❌ --project-dir must be an existing repository directory"); process.exit(2); }
+    const target = positionals[1] || (typeof flags.url === "string" ? flags.url : "");
+    const platform = requestedPlatform(flags, target);
+    if (!["ios", "android", "web"].includes(platform)) { console.error("❌ --platform must be ios|android|web"); process.exit(2); }
+    const engine = await engineImport();
+    let started = null;
+    try {
+      if (platform === "ios") {
+        requireMacFor("iOS focused navigation");
+        const sim = await engine.ensureBootedSim({ autoBoot:true });
+        if (sim.error) throw new Error(sim.error);
+        const bundleId = await resolveTargetOrExit(engine, target || projectDir);
+        const launch = iosLaunchOptions(flags, rest);
+        started = await engine.startIosInteractiveSession(bundleId, engine.explorationEnvFromArgs({ testEmail:flags.email, testPassword:flags.password, ...launch }));
+      } else if (platform === "android") {
+        const android = androidTarget(flags, target);
+        started = await engine.startAndroidInteractiveSession(android.appId, { serial:android.serial, apkPath:android.apkPath, clearData:flags["keep-data"] !== true });
+      } else {
+        if (!/^https?:\/\//i.test(target)) { console.error("❌ Web focus needs an http(s) target URL"); process.exit(2); }
+        started = await engine.startWebInteractiveSession(target);
+      }
+      if (started.error) throw new Error(started.error);
+      const focused = await engine.focusInteractiveSession({ projectDir, query, platform, mapPath:typeof flags.map === "string" ? flags.map : "" });
+      const { focusedTargetSummary } = await import(path.join(packageRoot, "mcp-server", "src", "focused-navigation.js"));
+      console.log(focusedTargetSummary(focused));
+      if (focused.execution?.status === "reached") {
+        console.log(`\n⚡ Reached in ${(focused.execution.steps || []).length} route action(s).\n`);
+        console.log(engine.formatScreen(focused.screenTitle, focused.elements));
+        const frame = await engine.captureInteractiveSessionFrame(Number(flags.width) || 900);
+        if (!frame.error) {
+          const out = saveShot(frame, typeof flags.out === "string" ? path.resolve(flags.out) : null, `focus-${Date.now()}.${frame.mimeType === "image/png" ? "png" : "jpg"}`);
+          console.log(`\n📸 Screenshot: ${out}`);
+        }
+      } else if (focused.execution?.status === "failed") {
+        console.error(`\n❌ Observed route stopped: ${focused.execution.reason}`);
+        process.exitCode = 1;
+      } else {
+        console.error("\nℹ️  Tapp located the source but did not drive an unobserved route. Ground the UI Map with `npx -y @aarwitz/tapp@latest init . --explore`.");
+      }
+    } catch (error) {
+      console.error(`❌ ${error.message || String(error)}`);
+      process.exitCode = 1;
+    } finally {
+      if (started) await engine.endInteractiveSession();
+    }
+    break;
+  }
+
   case "explore":
   case "qa": {
     // `explore` is the canonical verb (ADR-0005: exploration observes; the gate judges). `qa` is a
@@ -490,7 +627,7 @@ switch (command) {
         const modelPlatform = typeof flags.platform === "string" ? flags.platform.toLowerCase() : "";
         if (modelPlatform === "ios") requireMacFor("iOS testing");
         const onProgress = (p) =>
-          process.stderr.write(`\r🔍 Exploring… ${p.action}/${p.max || flags.actions || 60} actions · ${p.states} states observed   `);
+          writeProgress(`🔍 Exploring… ${p.action}/${p.max || flags.actions || 60} actions · ${p.states} states observed`);
         const r = await engine.runExploreTarget({
           projectDir: process.cwd(),
           platform: modelPlatform,
@@ -501,11 +638,12 @@ switch (command) {
           testPassword: flags.password,
           ...launchOptions,
           baselineFindings,
+          watch: flags.watch === true,
           surface: "cli",
           onProgress,
           onStatus: (t) => console.error(`ℹ️  ${t}`),
         });
-        process.stderr.write("\n");
+        finishProgress();
         if (r.error) { printEngineError(r); process.exit(1); }
         console.log(r.text);
         if (flags.json && typeof flags.json === "string") {
@@ -521,19 +659,23 @@ switch (command) {
       process.exit(2);
     }
     if (platform === "ios") requireMacFor("iOS testing");
+    if (flags.watch === true && platform !== "web") {
+      console.error("❌ --watch is currently available for web exploration only");
+      process.exit(2);
+    }
     if (platform !== "ios" && Object.keys(launchOptions).length) {
       console.error("❌ --launch-arg and --launch-env apply only to iOS targets");
       process.exit(2);
     }
     if (platform === "web" && !/^https?:\/\//i.test(target)) {
-      console.error("❌ Web QA needs an http(s) URL");
+      console.error("❌ Web exploration needs an http(s) URL");
       process.exit(2);
     }
     const bundleId = platform === "ios" ? await resolveTargetOrExit(engine, target) : null;
     const android = platform === "android" ? androidTarget(flags, target) : null;
     const progressMetric = platform === "web" ? "pages reached" : platform === "ios" ? "structural states observed" : "screens reached";
     const onProgress = (p) =>
-      process.stderr.write(`\r🔍 Exploring… ${p.action}/${p.max || flags.actions || 60} actions · ${p.states} ${progressMetric}   `);
+      writeProgress(`🔍 Exploring… ${p.action}/${p.max || flags.actions || 60} actions · ${p.states} ${progressMetric}`);
     const r = platform === "web"
       ? await engine.runQaWeb({
           url: target,
@@ -542,6 +684,7 @@ switch (command) {
           testEmail: flags.email,
           testPassword: flags.password,
           baselineFindings,
+          watch: flags.watch === true,
           surface: "cli",
           onProgress,
         })
@@ -565,7 +708,7 @@ switch (command) {
           surface: "cli",
           onProgress,
         });
-    process.stderr.write("\n");
+    finishProgress();
     if (r.error) {
       printEngineError(r);
       process.exit(1);
@@ -776,8 +919,22 @@ switch (command) {
       printEngineError(inst);
       process.exit(1);
     }
+    let modelRefresh = null;
+    try {
+      const { persistIosBuildValidation } = await import(path.join(packageRoot, "mcp-server", "src", "application-model.js"));
+      modelRefresh = await persistIosBuildValidation({
+        projectDir: dir,
+        bundleId: inst.bundleId,
+        container: built.container,
+        scheme: built.scheme,
+        configuration: built.configuration,
+      });
+    } catch (error) {
+      console.error(`⚠️  Build succeeded, but Tapp could not refresh the existing application model: ${error.message || String(error)}`);
+    }
     console.log(`🔨 Built ${path.basename(built.appPath)} (scheme ${built.scheme}) — installed as ${inst.bundleId}`);
-    console.log(`\nNext: tapp explore ${inst.bundleId}`);
+    if (modelRefresh) console.log(`   application model refreshed: ${modelRefresh.modelPath}`);
+    console.log(`\nNext: npx -y @aarwitz/tapp@latest explore ${inst.bundleId}`);
     break;
   }
 
@@ -860,8 +1017,12 @@ switch (command) {
     const { flags, positionals } = parseVerbArgs(rest);
     const verb = positionals[0] || "run";
     const flowPath = positionals[1] || (verb === "run" || verb === "validate" ? "" : verb);
+    if (verb === "example") {
+      console.log(`# Tapp Flow — deterministic, keyless replay\nname: sign-in-smoke\nplatform: web\nurl: https://example.test/login\nsteps:\n  - login:\n      email: $TEST_EMAIL\n      password: $TEST_PASSWORD\n  - wait_for: Dashboard\n  - assert_screen: Dashboard\n`);
+      break;
+    }
     if (!["run", "validate"].includes(verb) || !flowPath) {
-      console.error("usage: tapp flow run <flow.yml> [--platform ios|android|web] [--url URL] [--app-id ID] [--apk FILE] [--serial ID]\n       tapp flow validate <flow.yml>");
+      console.error("usage: tapp flow example\n       tapp flow run <flow.yml> [--platform ios|android|web] [--url URL] [--app-id ID] [--apk FILE] [--serial ID]\n       tapp flow validate <flow.yml>");
       process.exit(2);
     }
     const absolute = path.resolve(flowPath);
@@ -910,7 +1071,9 @@ switch (command) {
       invocation = ["bash", [path.join(packageRoot, "scripts", "run-flow.sh"), absolute, typeof flags["bundle-id"] === "string" ? flags["bundle-id"] : flow.app || ""]];
     }
     const result = spawnSync(invocation[0], invocation[1], { stdio: "inherit", env });
-    console.log(`\nEvidence: ${evidenceDir}`);
+    const evidenceWritten = fs.existsSync(evidenceDir) && fs.readdirSync(evidenceDir).length > 0;
+    if (evidenceWritten) console.log(`\nEvidence: ${evidenceDir}`);
+    else console.error("\n⚠️ Evidence unavailable — the platform runner did not write any artifacts for this Flow run.");
     process.exit(result.status ?? 1);
   }
 
@@ -991,7 +1154,7 @@ switch (command) {
       try {
         const adopted = adoptPrCoverageProposal({ projectDir, prPlanPath, item: flags.item, releasePlanPath: typeof flags["release-plan"] === "string" ? flags["release-plan"] : undefined });
         console.log(`📥 ${adopted.mode === "reconciled-existing" ? "Reconciled PR evidence into" : "Adopted"} ${adopted.item.name}${adopted.mode === "reconciled-existing" ? ` while preserving decision '${adopted.item.decision}'` : " as a pending release-plan item"}; no Task or contract was generated or trusted`);
-        console.log(`   plan: ${adopted.path}\n   next: tapp plan review ${adopted.path} --approve ${adopted.item.id}`);
+        console.log(`   plan: ${adopted.path}\n   next: npx -y @aarwitz/tapp@latest plan review ${adopted.path} --approve ${adopted.item.id}`);
       } catch (error) { console.error(`❌ Could not adopt PR coverage proposal: ${error.message || String(error)}`); process.exit(2); }
       break;
     }
@@ -1151,6 +1314,13 @@ switch (command) {
     const python = run("python3", ["--version"]);
     python.code === 0 ? ok("python3", `${python.stdout} (used by Flows)`) : bad("python3", "not found — Flow replay needs python3 + pyyaml (everything else works)");
 
+    const { storagePreflight } = await import(path.join(packageRoot, "mcp-server", "src", "environment-preflight.js"));
+    const storage = storagePreflight(tappHome);
+    if (storage.level === "blocked") { bad("Disk space", storage.message); healthy = false; }
+    else if (storage.level === "warning") console.log(`  ⚠️  Disk space — ${storage.message}`);
+    else if (storage.level === "ok") ok("Disk space", storage.message);
+    else console.log(`  ⬜ Disk space — ${storage.message || "could not be checked"}`);
+
     console.log("\n  Platforms:");
     if (process.platform === "darwin") {
       const xcode = run("xcode-select", ["-p"]);
@@ -1160,7 +1330,7 @@ switch (command) {
         const booted = bootedSims();
         ok("iOS", `${ver || "Xcode"}; ${booted.length ? `${booted[0].name} booted` : "no simulator booted yet"}`);
         const xctestrun = harnessXctestrun();
-        xctestrun ? ok("iOS harness cache", xctestrun) : console.log("  ⬜ iOS harness cache — builds on first use (or: tapp install)");
+        xctestrun ? ok("iOS harness cache", xctestrun) : console.log("  ⬜ iOS harness cache — builds on first use (or: npx -y @aarwitz/tapp@latest install)");
       } else {
         console.log("  ⬜ iOS — unavailable (install Xcode + simulator runtime)");
       }
@@ -1179,16 +1349,22 @@ switch (command) {
     }
 
     try {
-      await import("playwright");
-      ok("Web", "Playwright installed");
+      const { chromium } = await import("playwright");
+      let executable = "";
+      try { executable = chromium.executablePath(); } catch { /* report the missing browser below */ }
+      if (executable && fs.existsSync(executable)) {
+        ok("Web", `Playwright + Chromium (${executable})`);
+      } else {
+        console.log("  ⬜ Web — Playwright installed; Chromium browser missing (run: npx playwright install chromium)");
+      }
     } catch {
       console.log("  ⬜ Web — install Playwright in the app workspace: npm install -D playwright && npx playwright install chromium");
     }
 
     console.log(`\n  Home: ${tappHome}`);
     console.log(healthy
-      ? "\nReady. Start with:\n  npx -y @aarwitz/tapp open [target]\n  npx -y @aarwitz/tapp explore [target]"
-      : "\nFix the ❌ items above, then re-run: tapp doctor");
+      ? "\nReady. Start with:\n  npx -y @aarwitz/tapp@latest open [target]\n  npx -y @aarwitz/tapp@latest explore [target]"
+      : "\nFix the ❌ items above, then re-run: npx -y @aarwitz/tapp@latest doctor");
     process.exit(healthy ? 0 : 1);
   }
 
@@ -1263,7 +1439,13 @@ switch (command) {
       console.log(`✅ Actor '${name}' configured — ${result.actor.session} session · ${result.actor.provisioning} provisioning`);
       console.log(`   ${result.path}`);
       console.log(`   bindings: ${Object.entries(result.actor.credentials).map(([key, binding]) => `${key}=$${binding.env}`).join(", ") || "none"}`);
-      console.log("   No credential values were accepted or written. Rerun tapp init --refresh to update the application model.");
+      const { refreshExistingInitArtifacts } = await import(path.join(packageRoot, "mcp-server", "src", "application-model.js"));
+      let refreshed = null;
+      let refreshWarning = "";
+      try { refreshed = await refreshExistingInitArtifacts({ projectDir }); }
+      catch (error) { refreshWarning = error.message || String(error); }
+      console.log(`   No credential values were accepted or written.${refreshed ? ` Application model refreshed: ${refreshed.modelPath}` : " Run npx -y @aarwitz/tapp@latest init when you are ready to create the application model."}`);
+      if (refreshWarning) console.error(`⚠️  Actor was saved, but Tapp could not refresh the existing application model: ${refreshWarning}`);
     } catch (error) { console.error(`❌ Actor not configured: ${error.message || String(error)}`); process.exit(2); }
     break;
   }
@@ -1278,7 +1460,7 @@ switch (command) {
     const projectDir = fs.realpathSync(path.resolve(positionals[1] || (typeof flags["project-dir"] === "string" ? flags["project-dir"] : process.cwd())));
     const modelPath = typeof flags.model === "string" ? path.resolve(projectDir, flags.model) : existingProjectArtifactPath(projectDir, "application-model.json");
     if (!modelPath.startsWith(projectDir + path.sep) || !fs.existsSync(modelPath)) {
-      console.error(`❌ Application model not found inside the repository: ${modelPath}\n   Run tapp init --explore, review/generate/validate/promote the plan, then create the baseline.`);
+      console.error(`❌ Application model not found inside the repository: ${modelPath}\n   Run npx -y @aarwitz/tapp@latest init --explore, review/generate/validate/promote the plan, then create the baseline.`);
       process.exit(2);
     }
     let model;
@@ -1385,7 +1567,7 @@ switch (command) {
       catch { console.error(`❌ Repository directory not found: ${positionals[0] || flags["project-dir"] || process.cwd()}`); process.exit(2); }
       const modelPath = typeof flags.model === "string" ? path.resolve(projectDir, flags.model) : existingProjectArtifactPath(projectDir, "application-model.json");
       if (!modelPath.startsWith(projectDir + path.sep) || !fs.existsSync(modelPath)) {
-        console.error(`❌ Application model not found inside the repository: ${modelPath}\n   Run tapp init --explore first.`);
+        console.error(`❌ Application model not found inside the repository: ${modelPath}\n   Run npx -y @aarwitz/tapp@latest init --explore first.`);
         process.exit(2);
       }
       const actionRef = typeof flags["action-ref"] === "string" ? flags["action-ref"] : `aarwitz/tapp@v${pkg.version}`;
@@ -1502,17 +1684,18 @@ switch (command) {
   }
 
   default: {
-    console.log(`tapp v${pkg.version} — ship with proof. Autonomous exploration and deterministic release gates for iOS, Android, and web.
+    console.log(`tapp v${pkg.version} — agent-driven app testing for iOS, Android, and web.
 
-Core — explore, prove, gate (agents and humans can just run these — no server, no setup):
+Core — inspect, explore, gate (no Tapp account or server required):
   tapp explore [target]    Autonomous exploration → findings + evidence (an observation, NOT a
-                           release decision — run 'tapp ci' to gate a merge)
-                           (--platform ios|android|web · --app-id ID · --apk FILE · --actions N)
+                           release decision — run 'npx -y @aarwitz/tapp@latest ci' to gate a merge)
+                           (web: --watch · all: --platform ios|android|web · --actions N)
+  tapp focus "goal" [target] Source-locate a named screen/control and take the shortest observed route
   tapp contract run FILE   Replay a business-level release contract — the guarantees that must hold
   tapp ci ...              Merge-blocking release gate — explore + suites + baseline → pass/fail/inconclusive
                            (see: tapp ci --help)
 
-Primitives — an agent's eyes and hands (no setup):
+Primitives — an agent's eyes and hands:
   tapp open [target]       Launch the app → screen summary + screenshot saved to a file
                            (web: --tap TEXT · --wait-for TEXT · --out FILE)
   tapp tree [target]       Accessibility tree of the current screen (--json for every element)
@@ -1528,6 +1711,7 @@ Repository & release:
   tapp actor list [repo]   Inspect named actors, sessions, provisioning, and secret env bindings
 
 Advanced — deterministic suites, lifecycle & compilers:
+  tapp flow example        Print a complete starter Flow YAML (no target or MCP required)
   tapp flow run FILE       Replay a committed deterministic Flow (no AI/API key)
   tapp flow validate FILE  Validate a Flow without launching a target
   tapp task validate FILE  Validate a reusable deterministic Task (+ optional UI Map grounding)
@@ -1567,10 +1751,15 @@ Setup:
   tapp doctor     Check Xcode / simulators / toolchain
   tapp mcp        Start the MCP server on stdio (adds inline screenshots + interactive sessions)
 
+Agent Skill (recommended — so a short “Use Tapp to test this app” prompt is enough):
+  Any supported agent: npx -y skills add aarwitz/tapp --skill tapp
+  Claude skill + MCP:  claude plugin marketplace add aarwitz/tapp
+                       claude plugin install tapp@tapp
+
 MCP hookup (optional — for inline screenshots and the tap/type/inspect session loop):
-  Claude Code:   claude mcp add tapp -- npx -y @aarwitz/tapp mcp
+  Claude Code:   claude mcp add tapp -- npx -y @aarwitz/tapp@latest mcp
   Cursor/VS Code (mcp.json):
-    { "servers": { "tapp": { "type": "stdio", "command": "npx", "args": ["-y", "@aarwitz/tapp", "mcp"] } } }
+    { "servers": { "tapp": { "type": "stdio", "command": "npx", "args": ["-y", "@aarwitz/tapp@latest", "mcp"] } } }
 
 Then ask your agent things like:
   "Explore com.mycompany.app and show me what breaks"

package/docs/BROWSER-PRODUCT.md

@@ -12,7 +12,7 @@ in [`PRODUCT-ENGINE.md`](PRODUCT-ENGINE.md).
 ## Start locally
 
 ```bash
-npx -y @aarwitz/tapp app
+npx -y @aarwitz/tapp@latest app
 ```
 
 Tapp prints an authenticated one-time launch URL and opens it in the default browser. Use

package/docs/application-model.md

@@ -16,6 +16,15 @@ resolution actually builds and installs the detected Xcode container, the model
 scheme as runtime-observed validation and removes the corresponding confirmation blocker. Merely
 supplying a bundle id or prebuilt `.app` does not prove repository build configuration.
 
+A repository with more than one detected application target is never resolved by detection order
+during explicit initialization, even when a prior default exists. Bare `tapp init . --explore`
+prompts in a human TTY; non-interactive CLI/MCP callers receive
+exact `--platform`/`--target` commands before any build or write, and MCP also carries them as
+structured `target-selection-required` choices. The selected run records that target as the default
+for later bare `tapp explore`, but the application model retains the repository's other detected
+targets and their unmet coverage. The selected init run reports other-target setup gaps as deferred
+information rather than presenting them as failures of the target that was actually explored.
+
 ## First inspection
 
 ```bash
@@ -49,8 +58,8 @@ tapp init . --refresh --explore --platform web --url http://127.0.0.1:3000
 
 MCP clients use `tapp_init` with `operation: inspect|write|refresh|explore`. `inspect` is the safe
 default. `explore` writes real evidence, so the CLI rejects `--explore --dry-run`; the CLI also
-requires `--refresh --explore` once model/plan artifacts exist. Credentials are passed only to the
-runtime and are never written into the model, map, or plan.
+refreshes existing model/plan artifacts through the same decision-preserving semantics. Credentials
+are passed only to the runtime and are never written into the model, map, or plan.
 
 Successful repository-driven iOS build validation is portable and durable. The application model
 stores the repository-relative container, scheme, configuration, bundle id, and a
@@ -227,7 +236,7 @@ tapp baseline create . --platform web
 tapp baseline create . --platform web --from /path/to/tapp-report.json
 
 # Generate one target-aware job per model target plus a machine-readable manifest.
-tapp ci install . --action-ref aarwitz/tapp@v0.13.1
+tapp ci install . --action-ref aarwitz/tapp@v0.17.0
 ```
 
 Baseline creation rejects non-gate JSON, missing or mismatched target identity, platform mismatch,

package/docs/scenarios.md

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