@aarwitz/tapp 0.16.5 → 0.17.0-rc.10

package/bin/tapp.js

@@ -2,7 +2,7 @@
 // tapp CLI — ship with proof.
 //
 //   Zero-config verbs (the same engine the MCP tools use, exported by mcp-server/src/index.js):
-//   tapp qa <bundleId|appId|url> Autonomous QA → verdict + findings + evidence
+//   tapp explore <bundleId|appId|url> Autonomous exploration → findings + evidence (observation)
 //   tapp open <bundleId>     Launch app → screen summary + screenshot file
 //   tapp tree <bundleId>     Accessibility tree of the current screen
 //   tapp shot                Screenshot the booted simulator
@@ -28,13 +28,14 @@ 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.
-const tappHome = (process.env.TAPP_HOME || process.env.AUTOTAP_HOME || path.join(os.homedir(), ".tapp")).trim();
+// 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;
-fs.mkdirSync(tappHome, { recursive: true });
+// TAPP_HOME is created lazily (just before the switch) so `--help`, `help`, and `version` never
+// write anything — not even the home directory.
 
-const [, , command = "help", ...rest] = process.argv;
+let [, , command = "help", ...rest] = process.argv;
 
 function run(cmd, args, opts = {}) {
   const result = spawnSync(cmd, args, { encoding: "utf8", ...opts });
@@ -129,11 +130,32 @@ function repeatedFlagValues(argv, name) {
   return values;
 }
 
+function iosLaunchOptions(flags, argv) {
+  const appLaunchArgs = repeatedFlagValues(argv, "launch-arg");
+  let appLaunchEnv;
+  if (typeof flags["launch-env"] === "string") {
+    try {
+      const parsed = JSON.parse(flags["launch-env"]);
+      if (!parsed || Array.isArray(parsed) || typeof parsed !== "object" || Object.values(parsed).some((value) => typeof value !== "string")) {
+        throw new Error("expected a JSON object with string values");
+      }
+      appLaunchEnv = parsed;
+    } catch (error) {
+      console.error(`❌ --launch-env must be a JSON object with string values: ${error.message}`);
+      process.exit(2);
+    }
+  }
+  return {
+    ...(appLaunchArgs.length ? { appLaunchArgs } : {}),
+    ...(appLaunchEnv ? { appLaunchEnv } : {}),
+  };
+}
+
 const engineImport = () => import(path.join(packageRoot, "mcp-server", "src", "index.js"));
 
 function requireMacFor(what) {
   if (process.platform === "darwin") return;
-  console.error(`❌ ${what} requires macOS (Xcode + iOS simulator). The web beta runs anywhere: tapp qa https://localhost:3000`);
+  console.error(`❌ ${what} requires macOS (Xcode + iOS simulator). The web beta runs anywhere: tapp explore https://localhost:3000`);
   process.exit(1);
 }
 
@@ -184,6 +206,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) {
@@ -196,6 +238,57 @@ async function resolveTargetOrExit(engine, input) {
   return resolved.bundleId;
 }
 
+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]",
+    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]",
+    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]",
+    map: "tapp map build MARKERS [--platform PLATFORM] [--out FILE] [--replace]\ntapp map inspect [FILE]\ntapp map diff BEFORE AFTER [--comparable]",
+    pr: "tapp pr plan [--base REF|--changed-files FILE] [--head REF] [--platform PLATFORM] [--out FILE]\ntapp pr gate PLAN [gate target/options]\ntapp pr adopt PLAN --item ID [--project-dir DIR]",
+    plan: "tapp plan show [FILE]\ntapp plan review [FILE] --approve NAME[,NAME] --reject NAME[,NAME] --defer NAME[,NAME]\ntapp plan generate|validate|promote [FILE] [options]",
+    baseline: "tapp baseline create [repo] [--platform PLATFORM] [--target NAME] [--from GATE.json] [--replace]",
+    ci: "tapp ci ...\ntapp ci install [repo] [--out FILE] [--manifest FILE] [--dry-run] [--replace]",
+    actor: "tapp actor set NAME --email-env ENV --password-env ENV [--project-dir DIR]\ntapp actor list [repo]",
+    app: "tapp app [repo] [--no-open] [--port PORT]",
+    report: "tapp report [captureId|latest]",
+    doctor: "tapp doctor",
+    install: "tapp install",
+    mcp: "tapp mcp",
+  };
+  return usage[verb] || `tapp ${verb}`;
+}
+
+// Safe help: `--help`/`-h` on ANY verb prints the command reference and does NOTHING else — never
+// builds, launches, writes, or opens (ADR-0005 manual-testing requirement). `ci` keeps its own
+// richer `--help` (a safe usage print in ci-gate.sh); help/version don't need interception.
+// A bare `tapp --help` puts the flag in `command`, not `rest`; normalize it before the
+// per-verb interception so the root help path receives the same no-write guarantee.
+if (["--help", "-h"].includes(command)) {
+  command = "help";
+  rest = [];
+}
+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 = [];
+}
+
+// Create TAPP_HOME only for commands that actually use it — never for help/version/--help.
+if (!["help", "version", "--version", "-v"].includes(command)) {
+  fs.mkdirSync(tappHome, { recursive: true });
+}
+
 switch (command) {
   case "mcp": {
     // Agents spawn `tapp mcp`; the engine module is import-safe, so start explicitly.
@@ -229,7 +322,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);
@@ -239,31 +332,52 @@ 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,
+      runExploration: engine?.runInitExploration,
+      onProgress: (progress) => {
+        const activePlatform = progress.platform || platform;
+        process.stderr.write(`\r🔍 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" : "screens"} reached   `),
-        onStatus: (status) => console.error(`⏳ ${status}`),
-        outDir,
-        maxContracts,
-      });
+      result = await initializeProductProject(initOptions);
     } catch (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) process.stderr.write("\n");
-      console.error(`❌ Could not initialize repository: ${error.message || String(error)}`);
+      printEngineError({ error: `Could not initialize repository: ${failure.message || String(failure)}`, details: failure.details || {} });
       process.exit(2);
     }
     if (explore) process.stderr.write("\n");
@@ -280,7 +394,7 @@ switch (command) {
     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.verdict}${exploration.inconclusive ? " (inconclusive)" : ""} · ${exploration.uiMap.nodeCount} states · evidence: ${exploration.reportHtml || exploration.capture?.path || "capture recorded"}`);
+    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}`);
@@ -338,7 +452,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)}`);
@@ -387,9 +504,14 @@ 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 "explore":
   case "qa": {
+    // `explore` is the canonical verb (ADR-0005: exploration observes; the gate judges). `qa` is a
+    // hidden deprecated alias.
+    if (command === "qa") console.error("note: 'qa' is now 'explore' — 'qa' still works for now.\n");
     const { flags, positionals } = parseVerbArgs(rest);
-    const target = positionals[0] || "";
+    const launchOptions = iosLaunchOptions(flags, rest);
+    let target = positionals[0] || "";
     let baselineFindings;
     if (flags.baseline) {
       try {
@@ -401,21 +523,61 @@ switch (command) {
       }
     }
     const engine = await engineImport();
+    // Source-preparing bare explore (ADR-0005 §5): no explicit target + a repo application model →
+    // drive the model's default target end to end. Managed web is built/started/waited-for and
+    // always stopped; iOS is built + installed on the simulator; Android is built to an APK +
+    // installed. `--platform`/`--target` narrow which model target is chosen. With no model we fall
+    // through to the ordinary target resolution below, so nothing regresses.
+    if (!target && !flags["app-id"] && !flags.apk) {
+      const modelPath = existingProjectArtifactPath(process.cwd(), "application-model.json");
+      if (modelPath && fs.existsSync(modelPath)) {
+        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   `);
+        const r = await engine.runExploreTarget({
+          projectDir: process.cwd(),
+          platform: modelPlatform,
+          target: typeof flags.target === "string" ? flags.target : "",
+          maxActions: flags.actions,
+          timeout: flags.timeout,
+          testEmail: flags.email,
+          testPassword: flags.password,
+          ...launchOptions,
+          baselineFindings,
+          surface: "cli",
+          onProgress,
+          onStatus: (t) => console.error(`ℹ️  ${t}`),
+        });
+        process.stderr.write("\n");
+        if (r.error) { printEngineError(r); process.exit(1); }
+        console.log(r.text);
+        if (flags.json && typeof flags.json === "string") {
+          fs.writeFileSync(flags.json, JSON.stringify(r.structured, null, 2));
+          console.log(`\n📄 Full report JSON: ${flags.json} (pass as --baseline next run to diff regressions)`);
+        }
+        break;
+      }
+    }
     const platform = requestedPlatform(flags, target);
     if (!["ios", "android", "web"].includes(platform)) {
       console.error("❌ --platform must be ios|android|web");
       process.exit(2);
     }
     if (platform === "ios") requireMacFor("iOS testing");
+    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");
       process.exit(2);
     }
     const bundleId = platform === "ios" ? await resolveTargetOrExit(engine, target) : null;
     const android = platform === "android" ? androidTarget(flags, target) : null;
-    const unit = platform === "web" ? "pages" : "screens";
+    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} ${unit} reached   `);
+      process.stderr.write(`\r🔍 Exploring… ${p.action}/${p.max || flags.actions || 60} actions · ${p.states} ${progressMetric}   `);
     const r = platform === "web"
       ? await engine.runQaWeb({
           url: target,
@@ -443,7 +605,7 @@ switch (command) {
           bundleId,
           maxActions: flags.actions,
           timeout: flags.timeout,
-          args: { testEmail: flags.email, testPassword: flags.password, baselineFindings },
+          args: { testEmail: flags.email, testPassword: flags.password, baselineFindings, ...launchOptions },
           surface: "cli",
           onProgress,
         });
@@ -501,7 +663,6 @@ switch (command) {
       if (target.apkPath) await driver.install(target.apkPath);
       const snap = await driver.launch({ clearData: flags["clear-data"] === true });
       const data = await driver.screenshot();
-      await driver.forceStop();
       console.log(`🚀 Launched \`${target.appId}\` (Android)\n`);
       console.log(engine.formatScreen(snap.screenTitle, snap.elements));
       const out = typeof flags.out === "string" ? flags.out : path.join(tappHome, "shots", `${target.appId}-${Date.now()}.png`);
@@ -561,12 +722,17 @@ switch (command) {
       break;
     }
     if (platform === "android") {
-      const target = androidTarget(flags, positionals[0] || "");
+      const input = positionals[0] || "";
+      const hasTarget = !!(input || flags["app-id"] || flags.apk);
+      const target = hasTarget
+        ? androidTarget(flags, input)
+        : { serial: typeof flags.serial === "string" ? flags.serial : undefined };
       const { AndroidDriver } = await import(path.join(packageRoot, "mcp-server", "src", "android-driver.js"));
       const driver = new AndroidDriver(target);
       await driver.ensureDevice();
-      const snap = await driver.snapshot();
-      if (flags.json) console.log(JSON.stringify({ screenTitle: snap.screenTitle, elements: snap.elements }, null, 2));
+      if (target.apkPath) await driver.install(target.apkPath);
+      const snap = target.appId ? await driver.launch() : await driver.snapshot();
+      if (flags.json) console.log(JSON.stringify({ platform: "android", appId: target.appId || null, activity: snap.activity, screenTitle: snap.screenTitle, elements: snap.elements }, null, 2));
       else console.log(engine.formatScreen(snap.screenTitle, snap.elements));
       break;
     }
@@ -625,7 +791,7 @@ switch (command) {
     }
     console.log("📱 Installed on the booted simulator:\n");
     for (const a of la.apps) console.log(`  ${a.bundleId}  (${a.name})`);
-    console.log(`\nTest one: tapp qa <bundleId>`);
+    console.log(`\nTest one: tapp explore <bundleId>`);
     break;
   }
 
@@ -655,7 +821,7 @@ switch (command) {
       process.exit(1);
     }
     console.log(`🔨 Built ${path.basename(built.appPath)} (scheme ${built.scheme}) — installed as ${inst.bundleId}`);
-    console.log(`\nNext: tapp qa ${inst.bundleId}`);
+    console.log(`\nNext: tapp explore ${inst.bundleId}`);
     break;
   }
 
@@ -1057,15 +1223,21 @@ 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 qa [target]"
+      ? "\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");
     process.exit(healthy ? 0 : 1);
   }
@@ -1249,7 +1421,7 @@ switch (command) {
         replace: flags.replace === true,
       });
       console.log(`✅ Conclusive baseline established — ${selectedTarget.platform}:${selectedTarget.name}`);
-      console.log(`   ${written.validation.screensExplored} states · ${written.validation.actionsPerformed} actions · ${written.validation.suite.contracts} contracts · verdict ${written.validation.verdict}`);
+      console.log(`   ${written.validation.screensExplored} states · ${written.validation.actionsPerformed} actions · ${written.validation.suite.contracts} contracts · outcome ${written.validation.outcome}`);
       console.log(`   baseline: ${written.path}\n   source gate report: ${reportPath}`);
     } catch (error) { console.error(`❌ Baseline not written: ${error.message}`); process.exit(2); }
     break;
@@ -1348,9 +1520,15 @@ switch (command) {
     const runs = roots
       .flatMap((root) => fs.readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => path.join(root, e.name)))
       .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
-    const wanted = rest[0] && rest[0] !== "latest" ? runs.find((r) => path.basename(r) === rest[0]) : runs[0];
+    const hasMarkers = (dir) => fs.existsSync(path.join(dir, "ocqa-markers.txt"));
+    // `latest` (default) resolves to the newest *exploration* capture — the captures directory is
+    // also full of flow-*/scenario-* evidence dirs with no ocqa-markers.txt, and picking the newest
+    // of those made `tapp report` fail even though valid exploration captures existed. An explicitly
+    // named capture is honored as-is so a non-exploration capture still gets a clear "no markers".
+    const explicit = rest[0] && rest[0] !== "latest";
+    const wanted = explicit ? runs.find((r) => path.basename(r) === rest[0]) : runs.find(hasMarkers);
     if (!wanted) {
-      bad("No captures found", rest[0] ? `no capture named "${rest[0]}"` : "run a QA exploration first");
+      bad("No captures found", explicit ? `no capture named "${rest[0]}"` : "run an exploration first (no capture with exploration markers was found)");
       process.exit(1);
     }
     const { writeHtmlReport } = await import(path.join(packageRoot, "mcp-server", "src", "html-report.js"));
@@ -1360,7 +1538,9 @@ switch (command) {
       process.exit(1);
     }
     ok("Evidence report", out);
-    spawnSync("open", [out], { stdio: "ignore" });
+    // Only launch a browser from an interactive terminal — agents, scripts, and tests that invoke
+    // `tapp report` non-interactively get the path without a surprise GUI window.
+    if (process.stdout.isTTY) spawnSync("open", [out], { stdio: "ignore" });
     break;
   }
 
@@ -1372,15 +1552,32 @@ switch (command) {
   }
 
   default: {
-    console.log(`tapp v${pkg.version} — ship with proof. Autonomous QA and deterministic Flows for iOS, Android, and web.
+    console.log(`tapp v${pkg.version} — ship with proof. Autonomous exploration and deterministic release gates for iOS, Android, and web.
 
-Zero-config verbs (agents and humans can just run these — no server, no setup):
+Core — explore, prove, gate (agents and humans can just run these — no server, no setup):
+  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)
+  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):
   tapp open [target]       Launch the app → screen summary + screenshot saved to a file
                            (web: --tap TEXT · --wait-for TEXT · --out FILE)
-  tapp qa [target]         Autonomous QA → verdict + findings + evidence
-                           (--platform ios|android|web · --app-id ID · --apk FILE · --actions N)
   tapp tree [target]       Accessibility tree of the current screen (--json for every element)
                            (web: --tap TEXT · --wait-for TEXT)
+
+Repository & release:
+  tapp init [repo]         Detect targets and write the application model + reviewable release plan
+                           (--explore grounds the UI Map · --url URL · --platform · --dry-run · --refresh)
+  tapp baseline create [repo] Run/import a conclusive full gate and save a target-scoped baseline
+  tapp report [captureId]  Open the HTML evidence page for a capture (default: latest)
+  tapp ci install [repo]   Generate a reviewable target-aware GitHub workflow + CI manifest
+  tapp actor set NAME      Configure an actor using environment-variable names only (never values)
+  tapp actor list [repo]   Inspect named actors, sessions, provisioning, and secret env bindings
+
+Advanced — deterministic suites, lifecycle & compilers:
   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)
@@ -1388,38 +1585,32 @@ Zero-config verbs (agents and humans can just run these — no server, no setup)
   tapp task run FILE       Replay a Task directly on iOS, Android, or web
   tapp contract validate FILE  Validate a business-level TypeScript release contract
   tapp contract compile FILE   Compile a contract to the shared deterministic executor
-  tapp contract run FILE       Replay a release contract without AI or a coding agent
-  tapp pr plan --base REF      Select critical + diff-relevant contracts and report uncovered changes
-  tapp pr adopt PLAN --item ID Explicitly add an observed PR coverage proposal to the release plan
   tapp scenario run FILE   Replay an isolated multi-actor system Scenario (web)
   tapp scenario validate FILE  Validate actors, lifecycle, and deterministic steps
+  tapp pr plan --base REF      Select critical + diff-relevant contracts and report uncovered changes
+  tapp pr adopt PLAN --item ID Explicitly add an observed PR coverage proposal to the release plan
+  tapp plan show [FILE]    Inspect the proposed/accepted release-contract plan
+  tapp plan review [FILE]  Explicitly approve, reject, or defer proposed plan items
+  tapp plan generate [FILE] Generate compile-checked, untrusted contract drafts from approved Tasks
+  tapp plan validate [FILE] Replay drafts on a real target; trust only after all platforms pass
+  tapp plan promote [FILE] Move fully validated drafts into reviewed Tasks/contracts + map coverage
   tapp map build MARKERS    Build/merge the persistent platform-neutral UI Map
   tapp map inspect [FILE]   Inspect states, controls, platforms, and map validity
   tapp map diff A B         Diff observed UI structure without false reachability claims
-  tapp baseline create [repo] Run/import a conclusive full gate and save a target-scoped baseline
+
+Simulator & workspace:
   tapp shot                Screenshot the booted simulator → file path (--out file.jpg)
   tapp build [dir]         Build the iOS app in a repo for the simulator + install it (--scheme S)
   tapp apps                List apps installed on the booted simulator (with bundle ids)
-  tapp report [captureId]  Open the HTML evidence page for a capture (default: latest)
   tapp app [repo]          Optional local browser workspace for repository onboarding and review
                            (loopback-only; --no-open · --port PORT)
-  tapp init [repo]         Detect targets and write the application model + reviewable release plan
-                           (--explore builds/starts or connects, grounds the UI Map, then tears down)
-                           (--url URL · --platform PLATFORM · --dry-run · --refresh)
-  tapp actor list [repo]   Inspect named actors, sessions, provisioning, and secret env bindings
-  tapp actor set NAME      Configure an actor using environment-variable names only (never values)
-  tapp plan show [FILE]    Inspect the proposed/accepted release-contract plan
-  tapp plan review [FILE]  Explicitly approve, reject, or defer proposed plan items
-  tapp plan generate [FILE] Generate compile-checked, untrusted contract drafts from approved Tasks
-  tapp plan validate [FILE] Replay drafts on a real target; trust only after all platforms pass
-  tapp plan promote [FILE] Move fully validated drafts into reviewed Tasks/contracts + map coverage
-  tapp ci ...              Merge-blocking release gate — explore + flows + baseline diff (see: tapp ci --help)
-  tapp ci install [repo]   Generate a reviewable target-aware GitHub workflow + CI manifest
 
-  [target] is whatever you have — nothing (finds + builds the Xcode project in the current
-  dir, or falls back to the app on the simulator), a repo dir, a path/to/App.app, a bundle
-  id, an Android app id/APK (--platform android --app-id ...), or an http(s) URL.
-  For iOS you never need to know a bundle id up front.
+  [target] is whatever you have — nothing (in an initialized repo, bare 'tapp explore' drives the
+  application model's default target from source: managed web is built/started/stopped, iOS is
+  built + installed, Android is built to an APK + installed; otherwise it finds + builds the Xcode
+  project in the current dir, or falls back to the app on the simulator), a repo dir, a
+  path/to/App.app, a bundle id, an Android app id/APK (--platform android --app-id ...), or an
+  http(s) URL. For iOS you never need to know a bundle id up front.
 
 Setup:
   tapp install    Prebuild the exploration harness (~2 min; otherwise builds on first use)
@@ -1432,7 +1623,7 @@ MCP hookup (optional — for inline screenshots and the tap/type/inspect session
     { "servers": { "tapp": { "type": "stdio", "command": "npx", "args": ["-y", "@aarwitz/tapp", "mcp"] } } }
 
 Then ask your agent things like:
-  "Run tapp qa on com.mycompany.app — is it ship-ready?"
+  "Explore com.mycompany.app and show me what breaks"
   "Open the settings screen and show me the screenshot"
   "Drive the login flow and record it as a replayable test"
 

package/browser/app.js

@@ -243,12 +243,14 @@ function renderDecision(run) {
     return;
   }
   const report = latest.report;
-  const failed = report.gate?.failed === true;
-  const verdict = failed ? "blocked" : report.inconclusive ? "caution" : report.verdict || "caution";
-  card.className = `decision-card ${verdict}`;
-  $("#decision-title").textContent = failed ? "Do not merge" : report.inconclusive ? "Inconclusive" : report.verdict === "ready" ? "Ready to merge" : "Review required";
+  // The decision reflects the GATE outcome (pass/fail/inconclusive), not a ship verdict — exploration
+  // only observes (ADR-0005). Without a gate, it's an observation, not a merge decision.
+  const outcome = report.gate?.outcome || (report.gate?.failed === true ? "fail" : report.inconclusive ? "inconclusive" : report.gate ? "pass" : null);
+  const cssClass = { pass: "ready", fail: "blocked", inconclusive: "caution" }[outcome] || "caution";
+  card.className = `decision-card ${cssClass}`;
+  $("#decision-title").textContent = outcome === "fail" ? "Do not merge" : outcome === "inconclusive" ? "Inconclusive" : outcome === "pass" ? "Ready to merge" : "Observed — not a release decision";
   $("#decision-detail").textContent = report.gate?.reasons?.join(" · ") || report.headline || "Review the evidence below.";
-  $("#overview-evidence").innerHTML = `<div class="latest-run-line"><span class="verdict-dot ${esc(verdict)}"></span><div><strong>${esc(report.headline || pretty(verdict))}</strong><small>${esc(pretty(report.platform || "unknown"))} · ${compactDate(latest.createdAt)} · ${(report.contracts || []).filter((item) => item.passed).length}/${(report.contracts || []).length} contracts passed</small></div></div><p>${esc((report.gate?.reasons || ["No blocking release-gate reason reported."])[0])}</p>${reportLink(report)}`;
+  $("#overview-evidence").innerHTML = `<div class="latest-run-line"><span class="verdict-dot ${esc(cssClass)}"></span><div><strong>${esc(report.headline || pretty(cssClass))}</strong><small>${esc(pretty(report.platform || "unknown"))} · ${compactDate(latest.createdAt)} · ${(report.contracts || []).filter((item) => item.passed).length}/${(report.contracts || []).length} contracts passed</small></div></div><p>${esc((report.gate?.reasons || ["No blocking release-gate reason reported."])[0])}</p>${reportLink(report)}`;
 }
 
 function renderEvidence(runs) {
@@ -284,7 +286,11 @@ function renderRuns(runs) {
   $("#runs-list").innerHTML = runs.length ? runs.map((run) => {
     const report = run.report;
     const failed = report?.gate?.failed === true;
-    const status = !report ? run.status : failed ? "blocked" : report.inconclusive ? "inconclusive" : report.verdict || "completed";
+    // Status reflects the gate outcome (pass/fail/inconclusive), mapped to the existing CSS classes.
+    const status = !report ? run.status
+      : report.gate?.outcome === "fail" || failed ? "blocked"
+      : report.gate?.outcome === "inconclusive" || report.inconclusive ? "inconclusive"
+      : report.gate?.outcome === "pass" ? "ready" : "completed";
     return `<button class="run-row ${run.id === state.selectedRunId ? "selected" : ""}" data-run-id="${esc(run.id)}"><span class="run-status ${esc(status)}">${failed ? "×" : report ? "✓" : "…"}</span><span><strong>${esc(report?.headline || `Release run ${run.id.slice(-8)}`)}</strong><small>${compactDate(run.createdAt)} · ${esc(pretty(report?.platform || "unknown"))}</small></span><em>${esc(pretty(status))}</em></button>`;
   }).join("") : '<div class="empty">No release runs yet.</div>';
   const selected = runs.find((run) => run.id === state.selectedRunId) || runs[0];