@aarwitz/tapp 0.16.5 → 0.17.0-rc.2

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
@@ -30,11 +30,12 @@ const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "
 
 // 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();
+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);
 }
 
@@ -196,6 +218,47 @@ 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]",
+    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.
+if ((rest.includes("--help") || rest.includes("-h")) && !["help", "version", "--version", "-v", "ci"].includes(command)) {
+  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.
@@ -256,7 +319,7 @@ switch (command) {
         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   `),
+        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,
@@ -280,7 +343,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}`);
@@ -387,9 +450,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 +469,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 +551,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 +609,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 +668,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 +737,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 +767,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;
   }
 
@@ -1065,7 +1177,7 @@ switch (command) {
 
     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 +1361,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;
@@ -1372,15 +1484,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 +1517,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 +1555,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];

package/docs/BROWSER-PRODUCT.md

@@ -0,0 +1,75 @@
+# Browser Release Studio
+
+Status: current local-product contract as of 2026-08-08.
+
+The browser Release Studio is an **optional local workspace**, not the current launch surface — the
+**npm package (CLI + MCP + the GitHub Action) is the current objective** (ADR-0005). The Studio, the
+VS Code extension, the desktop app, and the future managed SaaS are separate/paused tracks. Web is
+also one application target beside iOS and Android; it is not a separate QA product. CLI, MCP, VS
+Code, the Action, desktop, and future managed SaaS all adapt the shared product operations described
+in [`PRODUCT-ENGINE.md`](PRODUCT-ENGINE.md).
+
+## Start locally
+
+```bash
+npx -y @aarwitz/tapp app
+```
+
+Tapp prints an authenticated one-time launch URL and opens it in the default browser. Use
+`--no-open` when copying the URL manually and `--port 4317` only when a fixed loopback port is
+needed. Drag/drop or Browse Folder copies source into a Tapp-owned workspace. Connect GitHub lists
+repositories authorized to the local `gh` session and makes a shallow isolated clone.
+`tapp app /path/to/repo` intentionally works directly in that checkout.
+
+The local server binds to `127.0.0.1`. It owns workspace paths; browser requests cannot submit an
+arbitrary server path. Mutations require an `HttpOnly` same-site session cookie, the exact local
+Origin, and an in-memory CSRF token. Application runtimes, repository credentials, and evidence stay
+in the local process/filesystem. This is a local trust boundary, not hosted multi-tenancy.
+
+## Product journey
+
+1. **Connect** a copied folder, an explicit checkout, or a repository authorized by local `gh`.
+2. **Detect and choose** an iOS, Android, or web target. Continue automatically only when the target
+   and configuration are conclusive.
+3. **Build, launch, and explore** the real simulator, emulator/device, or browser surface.
+4. **Understand the UI Map** through observed states, transitions, controls, provenance, and gaps.
+5. **Review intent** by approving, rejecting, deferring, or constraining a compact release plan.
+6. **Generate drafts** of Tasks and contracts. Drafts remain visibly untrusted.
+7. **Validate** approved drafts deterministically against the real target.
+8. **Promote** only validated artifacts into the canonical suite and refreshed Application Model.
+9. **Gate** with autonomous evidence plus the promoted deterministic suite.
+10. **Baseline** only a passing, conclusive, target-scoped gate.
+11. **Install CI** by previewing and writing a reviewable repository patch. Tapp does not commit,
+    push, create GitHub secrets, or enable branch protection.
+
+Successful semantic actions can be saved in `.tapp/flows/`; credential values are templated to
+environment references. Long-lived repository artifacts store binding names, not resolved secret
+values.
+
+## Verified reference journey
+
+`tests/browser-journey.test.js` drives the visible local browser against a fresh CommerceDemo copy.
+It exercises startup, a real live web surface and semantic action, UI Map creation, Flow recording
+and replay, proposal review, generation, deterministic validation, promotion, a first gate,
+baseline-aware rerun, and CI preview.
+
+The opt-in `tests/browser-native-journey.test.js` passed on 2026-08-06 against a booted iOS
+simulator: the browser built and installed a disposable DemoApp checkout, ran shared target
+preparation and exploration, rendered an observed UI Map, drove the live surface, and saved a
+repository-native iOS Flow. The equivalent Android browser journey was not verified in that audit
+because no emulator/device was connected.
+
+This evidence proves representative local journeys. It does not prove arbitrary frameworks,
+production credentials, third-party services, hosted execution, or complete inference of business
+intent.
+
+## Hosted relationship
+
+The future hosted application will present the same product journey through a different adapter: application
+accounts/organizations, GitHub App repository authorization, private storage, a durable queue, and
+isolated managed workers. It cannot reuse the loopback session, local `gh` authority, filesystem
+boundary, or in-memory ownership assumptions.
+
+The old hosted preview and `cloud/` prototype do not satisfy this boundary. The managed SaaS is a
+separate, paused track (see the private source repository); do not market or accept private
+repositories until its readiness gate passes.

package/docs/PRODUCT-ENGINE.md

@@ -0,0 +1,107 @@
+# One Tapp product engine
+
+Status: current product-engine contract as of 2026-08-08.
+
+Tapp has several interfaces, not several products. The source of truth for customer-critical
+operations is [`mcp-server/src/product-operations.js`](../mcp-server/src/product-operations.js).
+An interface may validate its transport and render a result; it must not redefine onboarding,
+review, trust, baseline, or gate semantics.
+
+## Product operation contract
+
+The shared engine owns these operations:
+
+| Operation | Authoritative result |
+|---|---|
+| `initializeProductProject` | detected targets, real exploration, Application Model, UI Map, release plan |
+| `readProductProject` | one current, read-only product snapshot for any interface |
+| `reviewProductPlan` | explicit approve/reject/defer decisions |
+| `generateProductPlan` | compile-checked but untrusted Task/contract drafts |
+| `validateProductPlan` | real-target, deterministic replay evidence |
+| `promoteProductPlan` | canonical Tasks/contracts, refreshed model/plan, updated map coverage |
+| `prepareProductCi` / `installProductCi` | target-aware workflow and machine-readable CI manifest |
+| `runProductGate` | autonomous evidence plus the committed deterministic suite and one gate decision |
+| `createProductBaseline` | conclusive, platform-and-target-specific comparison state |
+
+Deterministic contract execution is in
+[`mcp-server/src/product-execution.js`](../mcp-server/src/product-execution.js). It invokes platform
+executors directly; MCP does not shell through the CLI, and the browser does not shell through MCP.
+
+## Interfaces
+
+```text
+Browser Release Studio ─┐
+CLI                     ├── product-operations ── application model / UI Map / Tasks / contracts
+MCP                     ┘             │
+                                      └── deterministic executors / portable gate / evidence
+
+VS Code ── MCP client
+Desktop ── canonical artifact reader (migration to operation client remains)
+Action  ── portable gate adapter
+Hosted  ── tenant-aware SaaS adapter + queued isolated shared-operation workers (not built)
+```
+
+Current convergence:
+
+- the browser calls only shared product operations;
+- CLI initialization, plan lifecycle, deterministic draft validation, promotion, gate/baseline
+  lifecycle, and CI installation call the same operations. Native build preparation remains at the
+  adapter boundary and passes a resolved `.app` or APK into the shared gate;
+- MCP initialization, plan lifecycle, deterministic draft validation, promotion, baseline, and CI
+  installation call the same operations;
+- the GitHub Action and `runProductGate` call the same portable gate and evidence protocol;
+- VS Code remains a thin MCP client;
+- desktop reads the same `.tapp` artifacts but still has legacy import/build orchestration. It is
+  retained, not the launch UX, until that orchestration is removed;
+- `cloud/runner` is retained prototype evidence for exact checkout, versioned operation envelopes,
+  leases, and cleanup. It is not the production hosted adapter or an adequate arbitrary-customer
+  isolation boundary. The new SaaS must call these shared operations only through a tenant-aware,
+  queued worker contract (defined in the private source repository's SaaS architecture doc).
+
+## Canonical repository protocol
+
+New product behavior writes only `.tapp/`:
+
+```text
+.tapp/
+  project.json              # actors, env binding names, controlled lifecycle; never secret values
+  application-model.json    # detected/observed/declared product facts
+  ui-map.json               # grounded screen/action/transition graph
+  release-plan.json         # proposals and explicit human decisions
+  tasks/                    # reusable deterministic semantic operations
+  contracts/                # reviewed business guarantees
+  baselines/<platform>/     # conclusive target-specific comparison state
+  ci.json                   # generated CI installation manifest
+```
+
+`.tapp.yml` is the canonical run configuration, and `.tapp/` holds repository artifacts. These are
+the only names the runtime reads; the pre-rename `.autotap.yml`, `.autotap/`, and `AUTOTAP_*` inputs
+are no longer supported. Do not add another configuration format, and do not reintroduce a legacy
+reader. Only an explicit reviewed operation may write new repository artifacts.
+
+## Anti-duplication rules
+
+0. Exploration (`explore`, formerly `qa`) observes and surfaces findings + evidence + UI Map; it must
+   not render a release outcome. Only the gate (`runProductGate`) applies versioned deterministic
+   policy to findings + coverage + selected suites + an optional baseline and computes
+   `pass | fail | inconclusive` (ADR-0005, in the private source repository).
+1. Trust states (`pending`, `approved`, `validated-draft`, `promoted`) are computed by the engine.
+2. Interfaces render `readProductProject`; they do not infer readiness from file existence.
+3. Re-exploration refreshes evidence while preserving reviewed decisions everywhere.
+4. Promotion refreshes the Application Model immediately; no interface may show stale pre-promotion
+   requirements.
+5. Baselines are identified by platform and stable target id everywhere.
+6. An adapter-specific feature is not complete until its engine operation is useful without that
+   adapter.
+7. Equivalence tests should assert artifacts and structured results, not merely matching copy.
+
+## Remaining migration
+
+The next safe convergence work is deliberately narrow:
+
+1. replace desktop import/build orchestration with a local product-operation client;
+2. delete the two desktop detection/scaffolding paths only after equivalence fixtures pass;
+3. implement managed account, organization, and tenant authorization before connecting repositories;
+4. implement scoped GitHub authorization, private evidence, and disposable per-job
+   identity/simulator/credential isolation before accepting customer code;
+5. preserve CLI/MCP/VS Code/Action as adapters—do not rebuild their product logic.