@aarwitz/tapp 0.16.4 → 0.17.0-rc.1

package/AGENTS.md

@@ -8,16 +8,16 @@ Android emulators/devices, plus (beta) web apps in a real browser.
 Every core capability works as a plain command — no server, no config. `[target]` is
 optional: with nothing, tapp finds + builds the Xcode project in the cwd (or falls back to
 the app already on the simulator); it also accepts a repo dir, a `path/to/App.app`, a
-bundle id, or (qa only) an http(s) URL. You never need to know a bundle id up front.
+bundle id, or (web) an http(s) URL. You never need to know a bundle id up front.
 
 ```bash
-npx -y @aarwitz/tapp qa [target]     # autonomous QA → scoped release verdict + findings (≈ tapp_run_qa)
+npx -y @aarwitz/tapp explore [target]     # autonomous exploration → findings + evidence (observation, not a gate; ≈ tapp_explore)
 npx -y @aarwitz/tapp open [target]   # launch + screen summary + screenshot saved to a file (≈ tapp_open_app)
 npx -y @aarwitz/tapp tree [target]   # accessibility tree, --json for every element (≈ tapp_ui_tree)
 npx -y @aarwitz/tapp shot            # screenshot the booted sim → file path (≈ tapp_screenshot)
 npx -y @aarwitz/tapp apps            # what's installed on the simulator, with bundle ids
 npx -y @aarwitz/tapp build [dir]     # build the app in an Xcode repo + install it (≈ tapp_build)
-npx -y @aarwitz/tapp qa app.apk --platform android --app-id com.acme.app
+npx -y @aarwitz/tapp explore app.apk --platform android --app-id com.acme.app
 npx -y @aarwitz/tapp flow run .tapp/flows/smoke.yml  # committed, keyless E2E replay
 ```
 
@@ -30,21 +30,22 @@ loading or changing.
 Code's Read tool, Codex's view-image), open the saved screenshot path the CLI prints —
 that IS the screen. If you cannot (Cursor, VS Code Copilot), connect the MCP server
 instead: its tool results carry the screenshot inline. Screen *recordings* are for the
-human: `tapp qa` records the full exploration and embeds it in the report.html evidence
-page — tell the user the report path so they can watch it.
+human: on **iOS**, `tapp explore` records the full exploration and embeds it in the report.html
+evidence page (Android does not currently record video) — tell the user the report path so they can
+watch it.
 
 The interactive session/record loop is MCP-only (it needs a long-lived process). Flow replay is
 also available in the CLI. The rest of this playbook assumes the `tapp_*` MCP tools are connected. With
 MCP, the no-bundle-id path is: `tapp_build {projectDir}` (auto-detects + builds +
-installs, returns the bundle id) → `tapp_run_qa {appBundleId}`.
+installs, returns the bundle id) → `tapp_explore {appBundleId}`.
 
 ## Pick the right tool for the job
 
 | The user wants… | Use | NOT |
 |---|---|---|
-| "Show me / screenshot a screen" | `tapp_open_app` (launch + screenshot + tree, ~15s) | `tapp_run_qa` (a full multi-minute QA exploration) |
+| "Show me / screenshot a screen" | `tapp_open_app` (launch + screenshot + tree, ~15s) | `tapp_explore` (a full multi-minute QA exploration) |
 | "Tap through / drive / fill a form / log in" | `tapp_session_start` → `session_act` loop | repeated `open_app` calls (cold relaunch each time) |
-| "Is my app broken? Is it ship-ready? Find bugs" | `tapp_run_qa` — `appBundleId` for iOS, `androidAppId` for Android, `url` for owned web apps; web `ready` means the disclosed automated checks passed, not that copy/privacy/brand claims were reviewed | a manual session (QA exploration is autonomous) |
+| "Is my app broken? Find bugs" | `tapp_explore` — `appBundleId` for iOS, `androidAppId` for Android, `url` for owned web apps; returns an observation (findings + evidence), not a ship verdict — gate a merge with the CI gate (`tapp ci` CLI / the GitHub Action) + a contract | a manual session (exploration is autonomous) |
 | "Make this flow a repeatable test" | drive it in a session, then `tapp_flow_save`; replay with `tapp_flow_run` | re-driving it by hand every time |
 | "What's on screen right now?" | `tapp_screenshot` / `tapp_ui_tree` | relaunching the app |
 
@@ -80,12 +81,19 @@ Rules that prevent 90% of failures:
    auto-dismisses keyboards and retries), `not_found` (nothing matches — re-read the tree).
 6. One session at a time. `session_start` always begins from a fresh app launch.
 
-## Autonomous QA (`tapp_run_qa`)
+## Autonomous exploration (`tapp_explore`)
 
-Returns `{verdict, confidence, headline, screensExplored, actionsPerformed, findings[]}`.
+Exploration **observes** — it returns an observation, NOT a ship verdict or score. To get a release
+decision, run the deterministic gate (`tapp ci` / the GitHub Action). It applies versioned policy to
+the findings + coverage plus any selected Flows/Scenarios/contracts and an optional target-scoped
+baseline (both optional — a clean bootstrap can pass without them) and returns `pass | fail |
+inconclusive`.
+
+Returns `{kind:"tapp-exploration-run", headline, inconclusive, screensExplored, actionsPerformed,
+findingCounts, findings[]}` — **no** `verdict`, `confidence`, or `releaseScore`. Each finding carries
+`authority` (`deterministic` — marker-derived; model/vision findings would be `model-observed` and
+advisory). Report the finding counts and coverage; do not invent a scalar or a ship verdict.
 
-- `verdict`: `ready` | `caution` | `blocked`. **Trust it — it's deterministic.** Report it to the
-  user as-is; never soften a `blocked` or inflate a `caution`.
 - `inconclusive: true` means the run couldn't see enough (crash on launch, login wall). That is
   **not a pass** — tell the user what blocked exploration and what would unblock it.
 - Login walls: pass `testEmail`/`testPassword` (auto-typed into login forms), `appLaunchArgs`
@@ -93,11 +101,12 @@ Returns `{verdict, confidence, headline, screensExplored, actionsPerformed, find
   backend URL). If the result shows `inputFieldsEncountered` and you have no credentials, **ask
   the user** for them rather than re-running blind.
 - Diff two runs: pass the previous run's `findings` as `baselineFindings` → you get a
-  `regression` block (`new` / `persisting` / `resolved`, plus a CI `gate` signal).
-- On web, report the exact verdict but preserve its scope: Tapp deterministically checks technical
-  behavior such as failed requests, missing assets, placeholder links, and inert controls. It does
-  not validate marketing claims against APIs, API field privacy, brand consistency, or subjective
-  marketplace credibility unless an explicit reviewed test/contract covers them.
+  `regression` **comparison** (`new` / `persisting` / `resolved`) — an observation, not a gate. To gate
+  a merge on regressions, run the CI gate (`tapp ci` / the GitHub Action).
+- On web, preserve scope: Tapp deterministically checks technical behavior such as failed requests,
+  missing assets, and placeholder links. Dead-control probes are budget-capped advisory findings.
+  Tapp does not validate marketing claims against APIs, API field privacy, brand consistency, or
+  subjective marketplace credibility unless an explicit reviewed test/contract or verifier covers them.
 
 ## Flows (deterministic E2E tests)
 

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -1759,7 +1759,7 @@ class ExplorerTests: XCTestCase {
 
                 let issueTitle = "Dead end: \(titleStr)"
                 issues.append((type: "dead_end", severity: "medium", title: issueTitle, desc: "No interactable elements found"))
-                print("OCQA_ISSUE:{\"type\":\"dead_end\",\"severity\":\"medium\",\"title\":\"\(escapedTitle)\",\"screen\":\"\(escapedTitle)\",\"step\":\(actionCount)}")
+                print("OCQA_ISSUE:{\"type\":\"dead_end\",\"severity\":\"medium\",\"title\":\"\(escapeJSON(issueTitle))\",\"screen\":\"\(escapedTitle)\",\"step\":\(actionCount)}")
 
                 // tryGoBack does swipe-down as its last resort (sheet dismiss)
                 let preBackTitle = titleStr

package/README.md

@@ -12,21 +12,24 @@ It turns a repository and real product into an observed UI Map, a compact review
 suite, and an inspectable merge decision.
 
 Coding agents can write the code, and (with Playwright & friends) they can even drive the app.
-What nobody gives them is **judgment**: did it actually work? tapp explores your app like a user —
-no test code, no app changes — detects what's broken, and commits to a verdict your merge queue
-can trust: `ready`, `caution`, or `blocked`, with evidence.
+What nobody gives them is **proof it works**. tapp explores your app like a user — no test code,
+no app changes — and surfaces what's broken, with evidence. Then a deterministic gate applies
+versioned policy to that evidence — the findings and coverage, any selected deterministic suites
+(Flows/Scenarios/contracts), and, when available, a target-scoped baseline — and returns a merge
+decision your queue can trust: `pass`, `fail`, or `inconclusive`. Exploration **observes**; the gate
+**judges** — never a soft "ship-ready" guess.
 
-Three platforms, one judgment layer:
+Three platforms, one observe-and-gate engine:
 
-- **iOS** — the missing Playwright for iOS. tapp is hands *and* judgment: a generic XCUITest
+- **iOS** — the missing Playwright for iOS. tapp is hands *and* eyes: a generic XCUITest
   harness drives any app on the simulator via the accessibility surface. Native — no Appium,
   no WebDriverAgent.
 - **Android** — black-box native driving through ADB + UIAutomator. Install an APK, target its
-  application id, and run the same QA, committed Flows, evidence, and regression gate. The app
-  does not link a Tapp SDK.
+  application id, and run the same exploration, committed Flows, evidence, and regression gate. The
+  app does not link a Tapp SDK.
 - **Web (beta)** — built *on* Playwright. Your agent already has browser hands; tapp adds the
   autonomous exploration, the deterministic detectors (uncaught exceptions, failed requests,
-  dead buttons, broken links, placeholder `href="#"` links, error pages), and the same verdict.
+  dead buttons, broken links, placeholder `href="#"` links, error pages), and the same gate.
 
 ```
 you:    "Add a logout button to the settings screen"
@@ -40,17 +43,17 @@ agent:  "Done — and here it is working on the simulator: [screenshot]"
 Requirements: **Node ≥ 18**. iOS needs **macOS + Xcode**; Android needs `adb` plus a connected
 emulator/device; web needs Playwright + Chromium.
 
-From the app repository, let the agent see the current screen and then ask for a release verdict:
+From the app repository, let the agent see the current screen and then explore it:
 
 ```bash
 npx -y @aarwitz/tapp open   # builds/launches as needed; prints a screenshot path + screen summary
-npx -y @aarwitz/tapp qa     # explores the real app; prints verdict, findings, and evidence report
+npx -y @aarwitz/tapp explore     # explores the real app; prints findings + evidence (an observation, not a gate)
 ```
 
 Claude Code can read the saved image with its file-reading tool; Codex can open it with
-`view_image`. The agent should report what the screenshot proves, preserve Tapp's exact
-`ready`/`caution`/`blocked` verdict, and link the HTML evidence report. No server, account, config
-file, test code, API key, or bundle id is required for this loop.
+`view_image`. The agent should report what the screenshot proves, relay the exploration findings
+as-is (an observation, not a merge decision — `tapp ci` gates that), and link the HTML evidence
+report. No server, account, config file, test code, API key, or bundle id is required for this loop.
 
 The product, executable, and package leaf are all Tapp: npm distributes it as
 `@aarwitz/tapp`, while the installed command remains `tapp`.
@@ -77,7 +80,7 @@ npx -y @aarwitz/tapp baseline create . --platform web
 npx -y @aarwitz/tapp ci install .
 ```
 
-The baseline command writes only after autonomous QA and every selected deterministic suite pass
+The baseline command writes only after exploration and every selected deterministic suite pass
 conclusively. It stores `.tapp/baselines/<platform>/<target-id>.json`; the generated workflow
 uses that exact target identity so two apps on the same platform never share a baseline. `ci
 install` writes `.github/workflows/tapp.yml` plus `.tapp/ci.json`, refuses unresolved build
@@ -96,7 +99,7 @@ npx -y @aarwitz/tapp apps            # what's installed on the simulator (names
 npx -y @aarwitz/tapp build [dir]     # just build + install (scheme auto-detected)
 ```
 
-Web (beta): `npx -y @aarwitz/tapp qa http://localhost:3000` *(one-time setup:
+Web (beta): `npx -y @aarwitz/tapp explore http://localhost:3000` *(one-time setup:
 `npm i -g playwright && npx playwright install chromium`)*
 
 Focused web inspection waits briefly for loading states to settle. If a consent or location modal
@@ -110,7 +113,7 @@ npx -y @aarwitz/tapp tree https://example.com --tap "Not now" --wait-for "Dashbo
 Android:
 
 ```bash
-npx -y @aarwitz/tapp qa path/to/app-debug.apk --platform android --app-id com.acme.app
+npx -y @aarwitz/tapp explore path/to/app-debug.apk --platform android --app-id com.acme.app
 npx -y @aarwitz/tapp open com.acme.app --platform android
 ```
 
@@ -124,7 +127,7 @@ npx -y @aarwitz/tapp doctor     # verify Xcode / simulators / toolchain
 
 `npx -y @aarwitz/tapp app .` opens a local Release Studio for people who want visual repository
 onboarding, release-plan review, and CI preparation. It is not required for the coding-agent
-`open`/`qa` workflow.
+`open`/`explore` workflow.
 
 ### MCP hookup (optional)
 
@@ -156,7 +159,7 @@ args = ["-y", "@aarwitz/tapp", "mcp"]
 **Any other MCP client:** stdio command `npx -y @aarwitz/tapp mcp`.
 
 Then ask your agent:
-> "Run tapp qa on my app — is it ship-ready?"
+> "Explore my app and show me what breaks."
 > "Open com.mycompany.app on the simulator and screenshot the home screen."
 > "Log in with test@example.com, drive to checkout, and record it as a replayable test."
 
@@ -168,7 +171,7 @@ Then ask your agent:
 | 📸 | `tapp_screenshot` | Whatever's on the sim right now, as an inline image. |
 | 🌳 | `tapp_ui_tree` | The accessibility tree of the current screen (ids, labels, hittability). |
 | 🕹 | `tapp_session_start/act/end` | **Interactive driving** — the Playwright loop. App launches once; each act (tap/type/swipe/back/wait) returns the fresh tree. |
-| 🧪 | `tapp_run_qa` | **Autonomous QA** — explores with no authored test, returns `{verdict, releaseScore, findings[]}`. Takes `appBundleId` (iOS), `androidAppId` (Android), or `url` (web). |
+| 🔭 | `tapp_explore` | **Autonomous exploration** — explores with no authored test, returns an observation `{kind, headline, inconclusive, findingCounts, findings[]}` (no verdict/score — the deterministic gate judges). Takes `appBundleId` (iOS), `androidAppId` (Android), or `url` (web). |
 | 🧭 | `tapp_init` | **Repository import** — detect targets; optionally explore a real surface; persist the shared UI Map; construct the evidence-classified model and grounded release plan. |
 | 👤 | `tapp_actor_config` | **Actor/session setup** — store roles, isolation/provisioning, and environment-variable names without accepting or persisting credential values. |
 | ✅ | `tapp_release_plan` | **Release-plan lifecycle** — inspect, approve/reject/defer, generate, real-target validate, and explicitly promote proposed guarantees without silent test edits. |
@@ -189,40 +192,43 @@ The desktop Coverage view reads the same `.tapp/application-model.json`,
 does not maintain a separate product model. Map nodes identify both the real launch entry and the
 deterministic per-platform navigation root used for bounded changed-surface replay.
 
-## The verdict you can trust
-
-**Adaptive exploration, deterministic judgment.** Exploration is adaptive — two runs may
-traverse different paths through your app. Judgment is deterministic: the same evidence
-trace always produces the same findings, the same score, and the same verdict — no LLM variability
-in the decision loop. PR gating keys on the **regression diff**
-(stable finding signatures vs. a baseline), so it reacts to what *changed*, not to
-run-to-run path variance. For critical user journeys, committed **Tasks and Flows** provide the stable CI
-suite: reusable semantic actions, exact assertions, condition-based waits, fresh launch state, bounded timeouts,
-and evidence on failure. We call this *flake-resistant*, not magically flake-free—backend outages,
-unstable test data, and poorly identified controls can still make any E2E test fail.
-
-**A release score, not "confidence."** The 0–100 number is a heuristic quality score from
-fixed, documented deductions — we don't call it confidence because it isn't calibrated
-probability. Calibrating it against seeded-fault benchmarks is ongoing work; until then it
-ranks runs, it doesn't promise odds.
-
-`tapp_run_qa` explores like a user — accessibility surfaces on iOS/Android and a real browser on web —
-and detects crashes, failed sign-ins, dead buttons, stuck loading screens, error surfaces,
-navigation loops, and dead ends (plus, on web: uncaught JS exceptions, failed/5xx requests,
-broken links and assets, and visible placeholder links with no destination). The verdict is
-**deterministic** (no LLM in the run loop) and **honest**:
-
-- `blocked` — a release-blocking issue was found.
-- `caution` — issues to review, or the run couldn't see enough.
-- `ready` — genuinely explored with no detected blockers in the checks that ran. **A shallow run
-  is never `ready`** — if the
-  app crashed on launch or a login wall blocked exploration, you get `inconclusive: true`,
-  not a false pass. Absence of findings is not a pass.
-
-Web beta presents a `ready` result as **AUTOMATED CHECKS PASSED**, not “ship-ready.” Its report
-explicitly excludes content/claim accuracy, privacy and API data minimization, brand/SEO
-consistency, and subjective visual credibility. Those require reviewed contracts, privacy review,
-or human/vision judgment; a green technical crawl must not imply they were validated.
+## Observation you can read, judgment you can trust
+
+**Exploration observes; the gate judges.** Exploration is adaptive — two runs may traverse different
+paths — and it produces an **observation**, never a ship verdict: findings + coverage + evidence. The
+**gate** is deterministic: the same evidence trace, contracts, and baseline always produce the same
+outcome — `pass`, `fail`, or `inconclusive` — with no LLM in the decision loop. PR gating keys on the
+**regression diff** (stable finding signatures vs. a baseline), so it reacts to what *changed*, not to
+run-to-run path variance. For critical user journeys, committed **Tasks and Flows** provide the stable
+CI suite: reusable semantic actions, exact assertions, condition-based waits, fresh launch state,
+bounded timeouts, and evidence on failure. We call this *flake-resistant*, not magically flake-free —
+backend outages, unstable test data, and poorly identified controls can still make any E2E test fail.
+
+**No scores, no soft verdicts.** Exploration reports deterministic findings, advisory budget-capped
+control probes, and concrete coverage — never a 0–100 number or a "ready/ship" label a shallow crawl
+can't honestly earn. The merge decision comes only from the gate: reviewed contracts, committed
+Flows/Scenarios, and baseline regressions.
+
+`tapp_explore` explores like a user — accessibility surfaces on iOS/Android and a real browser on web
+— and detects crashes, failed sign-ins, dead buttons, stuck loading screens, error surfaces,
+navigation loops, and dead ends (plus, on web: uncaught JS exceptions, failed/5xx requests, broken
+links and assets, and visible placeholder links with no destination). The observation is honest about
+its limits:
+
+- It **surfaces findings**; it does not pronounce "ready." **A shallow run is never a pass** — if the
+  app crashed on launch or a login wall blocked exploration, you get `inconclusive: true`, not a false
+  green. Absence of findings is not a pass.
+- The **gate** turns findings + coverage + your reviewed contracts + a baseline into `pass` / `fail` /
+  `inconclusive` (`inconclusive` fails closed). Deterministic — no LLM in the run loop.
+- An exploratory crawl explicitly **excludes** content/claim accuracy, privacy and API data
+  minimization, brand/SEO consistency, and subjective visual credibility. Those require reviewed
+  contracts, privacy review, or human/vision judgment; a crawl must not imply they were validated.
+
+For a business guarantee such as “every coach is insured,” use a deterministic app-owned verifier
+endpoint that returns success only when the invariant holds, then require that status and the
+customer-visible claim in a release contract. The current DSL does not yet read arbitrary JSON
+response bodies or compare a cross-origin API payload directly with page copy; use a verifier or an
+explicit CI preflight rather than assuming exploration inferred the guarantee.
 
 Apps behind a login? Pass `testEmail`/`testPassword` (typed into the login form automatically),
 `appLaunchArgs` (e.g. `["--uitesting"]` if your app supports a bypass), or explicit `loginSteps`
@@ -341,30 +347,30 @@ your agent proves its UI work instead of claiming it:
 This repo uses tapp (https://github.com/aarwitz/tapp) to verify UI work on a real app surface
 (iOS simulator, Android emulator/device, or a browser for web). After any UI change, run `npx -y @aarwitz/tapp open` from the
 repo root (it finds and builds the Xcode project itself) and look at the screenshot it saves as
-proof. Before declaring a feature done, run `npx -y @aarwitz/tapp qa` (or `qa <url>` for web) and
-report the ship/no-ship verdict. A change is not "done" until it has been seen working.
+proof. Before declaring a feature done, run `npx -y @aarwitz/tapp explore` (or `explore <url>` for web)
+and report the findings + evidence. A change is not "done" until it has been seen working.
 (If the tapp MCP server is connected, the tapp_* tools do the same with inline screenshots —
-tapp_build builds + installs the app and returns the bundle id for tapp_run_qa.)
+tapp_build builds + installs the app and returns the bundle id for tapp_explore.)
 ```
 
 ## How it works
 
 Every driver speaks one protocol: structured `OCQA_*` markers (state, actions, issues,
-transitions) that the judgment layer parses into trees, screenshots, findings, and the verdict.
+transitions) that the engine parses into trees, screenshots, findings, coverage, and the gate outcome.
 On **iOS**, a generic **XCUITest harness** attaches to any app by bundle id — no SDK or app code
 changes — and acts through the accessibility tree. On **Android**, ADB + UIAutomator provide the
 same black-box driver contract. On **web** (beta), a deterministic **Playwright crawler** does the
 same in a real browser. Same detectors' spirit,
-same dedup, same regression gate, same honest verdict. Core exploration, evidence collection, and
-verdict calculation run entirely locally — no telemetry, nothing phones home. Optional AI
+same dedup, same regression gate, same honest `pass`/`fail`/`inconclusive` outcome. Core exploration,
+evidence collection, and gate evaluation run entirely locally — no telemetry, nothing phones home. Optional AI
 features are explicit: finding enrichment requires `TAPP_ENABLE_REMOTE_AI=1` (an ambient
 API key alone never changes data handling), and AI flow generation / `assert_ai` only run
 when you invoke them; these send selected metadata (screen names, finding titles) to your
 configured model provider. Runtime configuration uses `TAPP_*` environment variables. Repository
-artifacts live under `.tapp/`, and desktop run configuration uses `.tapp.yml`. Existing
-`.autotap/`, `.autotap.yml`, and `AUTOTAP_*` inputs remain readable as migration fallbacks; when
-both names exist, Tapp uses the canonical one. Rename the old directory/config in your next
-reviewed repository change—no secrets or evidence formats need to be rewritten.
+artifacts live under `.tapp/`, and desktop run configuration uses `.tapp.yml`. These are the only
+names Tapp reads: the pre-rename `.autotap/`, `.autotap.yml`, and `AUTOTAP_*` inputs are no longer
+supported. If you still have an old directory or config, rename it to the `.tapp` names in a
+reviewed change—no secrets or evidence formats need to be rewritten.
 
 Committed Flow replay, recording a driven session, autonomous exploration, exact assertions,
 regression comparison, and CI gating require **no API key and no coding agent at runtime**. AI is

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 });
@@ -133,7 +134,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 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 +197,20 @@ async function resolveTargetOrExit(engine, input) {
   return resolved.bundleId;
 }
 
+// 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(`ℹ️  '${command} --help' — showing the command reference (--help never builds, launches, writes, or opens):\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.
@@ -280,7 +295,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 +402,13 @@ 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] || "";
+    let target = positionals[0] || "";
     let baselineFindings;
     if (flags.baseline) {
       try {
@@ -401,6 +420,41 @@ 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} reached   `);
+        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,
+          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");
@@ -625,7 +679,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 +709,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 +1119,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 +1303,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 +1426,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.
+
+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)
 
-Zero-config verbs (agents and humans can just run these — no server, no setup):
+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 +1459,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 +1497,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"