@aarwitz/tapp 0.17.0-rc.13 → 0.17.0-rc.15

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "tapp",
-  "description": "The official Tapp plugin: one agent skill and MCP tools for testing iOS, Android, and web apps on real surfaces.",
+  "description": "The official Tapp plugin: the agent skill and MCP tools for testing real iOS, Android, and web app surfaces.",
   "owner": {
     "name": "Aaron Horowitz",
     "url": "https://github.com/aarwitz"
@@ -12,12 +12,12 @@
         "source": "npm",
         "package": "@aarwitz/tapp"
       },
-      "description": "Test real iOS, Android, and web apps with Tapp. Includes the Tapp agent skill plus MCP hands, eyes, exploration, replayable Flows, and deterministic release evidence.",
+      "description": "Give Claude hands and eyes on iOS, Android, and web apps, with exploration, replayable flows, evidence, and deterministic CI gates.",
       "author": {
         "name": "Aaron Horowitz",
         "url": "https://github.com/aarwitz"
       },
-      "homepage": "https://github.com/aarwitz/tapp",
+      "homepage": "https://runtapp.com/",
       "license": "MIT",
       "keywords": [
         "ios",

package/.claude-plugin/plugin.json

@@ -1,12 +1,12 @@
 {
   "name": "tapp",
-  "description": "Test real iOS, Android, and web apps with Tapp. Includes the Tapp agent skill plus MCP hands, eyes, exploration, replayable Flows, and deterministic release evidence.",
-  "version": "0.17.0-rc.13",
+  "description": "Give Claude hands and eyes on iOS, Android, and web apps, with exploration, replayable flows, evidence, and deterministic CI gates.",
+  "version": "0.17.0-rc.15",
   "author": {
     "name": "Aaron Horowitz",
     "url": "https://github.com/aarwitz"
   },
-  "homepage": "https://github.com/aarwitz/tapp",
+  "homepage": "https://runtapp.com/",
   "repository": "https://github.com/aarwitz/tapp",
   "license": "MIT",
   "keywords": [
@@ -24,7 +24,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@aarwitz/tapp@0.17.0-rc.13",
+        "@aarwitz/tapp@0.17.0-rc.15",
         "mcp"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}"

package/AGENTS.md

@@ -1,11 +1,13 @@
 # Tapp agent playbook
 
-You (the agent) have Tapp: hands, eyes, and judgment on real app surfaces — iOS simulators,
-Android emulators/devices, plus (beta) web apps in a real browser.
+You (the agent) have Tapp: hands and eyes on real app surfaces — iOS simulators, Android
+emulators/devices, plus (beta) web apps in a real browser. Release judgment belongs only to Tapp's
+repository-connected deterministic gate.
 
 ## No MCP connected? Just run the CLI
 
-Every core capability works as a plain command — no server, no config. `[target]` is
+The core inspect, explore, replay, and gate capabilities work as plain commands — no Tapp account,
+server, or global install. `[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 (web) an http(s) URL. You never need to know a bundle id up front.
@@ -57,7 +59,7 @@ installs, returns the bundle id) → `tapp_explore {appBundleId}`.
 
 | The user wants… | Use | NOT |
 |---|---|---|
-| "Show me / screenshot a screen" | `tapp_open_app` (launch + screenshot + tree, ~15s) | `tapp_explore` (a full multi-minute QA exploration) |
+| "Show me / screenshot a screen" | `tapp_open_app` (launch + screenshot + tree, ~15s) | `tapp_explore` (a full multi-minute 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? 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 |
@@ -67,6 +69,7 @@ installs, returns the bundle id) → `tapp_explore {appBundleId}`.
 
 ```
 tapp_session_start { appBundleId: "com.acme.app" }     → fresh launch + initial tree
+tapp_session_act   { action: "login", email: "qa@x.com", password: "…" } → atomic fill + submit + verify
 tapp_session_act   { action: "tap",  id: "Email" }      → tap by a11y id OR visible label
 tapp_session_act   { action: "type", text: "qa@x.com" } → types into the focused field
 tapp_session_act   { action: "tap",  id: "Sign In" }
@@ -90,7 +93,8 @@ Rules that prevent 90% of failures:
 3. **`wait` after anything async** (navigation, network loads): `{action: "wait", id|text, timeoutMs}`.
    Never assume the next screen is instantly there.
 4. **Tap the field before typing** — `type` goes to the focused field. Tap email → type email →
-   tap password → type password.
+   tap password → type password. For sign-in, prefer the atomic `login` action: it records a
+   secret-templated replay step and avoids native secure-field refocus behavior.
 5. Tap results: `ok` (landed), `not_hittable` (exists but disabled/covered — the harness
    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.
@@ -134,6 +138,8 @@ without a coding agent, model, subscription, or API key. AI generation and `asse
   deterministic assertions, same result every time. A failed assertion is a finding.
 - **Generate:** `tapp_flow_generate { goal: "log in and add the first item to cart" }` —
   grounded in the app's actually-explored screens, so it can't invent steps.
+- **Discover the file format without MCP:** `npx -y @aarwitz/tapp@latest flow example` prints a
+  complete starter Flow; `tapp flow validate <file>` checks it without launching a target.
 
 ## Setup facts (tell the user when relevant)
 

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -765,6 +765,12 @@ class ExplorerTests: XCTestCase {
             case "type":
                 status = sessionType(value, id: target.isEmpty ? nil : target) ? "pass" : "fail"
                 if status == "fail" { detail = "no field ‘\(target)’ to type into" }
+            case "login":
+                let email = subst((step["email"] as? String) ?? "$TEST_EMAIL")
+                let password = subst((step["password"] as? String) ?? "$TEST_PASSWORD")
+                let result = sessionLogin(email: email, password: password)
+                status = result.status == "ok" ? "pass" : "fail"
+                if status == "fail" { detail = result.detail.isEmpty ? result.status : result.detail }
             case "swipe":
                 switch target.lowercased() { case "down": app.swipeDown(); case "left": app.swipeLeft(); case "right": app.swipeRight(); default: app.swipeUp() }
             case "back":
@@ -1029,6 +1035,11 @@ class ExplorerTests: XCTestCase {
 
         let testEmail = resolve("OCQA_TEST_EMAIL")
         let testPassword = resolve("OCQA_TEST_PASSWORD")
+        if resolve("OCQA_CREDENTIALS_EXPLICIT") == "1" {
+            // Presence only: never print, persist, or expose credential values. Report rebuilding
+            // needs this durable marker to distinguish "not supplied" from "supplied but unused".
+            print("OCQA_STATE:credentials_supplied")
+        }
 
         // --- Explicit login replay (config-driven): a recorded type/tap/wait sequence for custom
         // login UIs the heuristic preamble below can't parse. When configured it takes precedence. ---

package/README.md

@@ -1,4 +1,4 @@
-# tapp — ship with proof
+# Tapp
 
 [![CI](https://github.com/aarwitz/tapp/actions/workflows/ci.yml/badge.svg)](https://github.com/aarwitz/tapp/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/%40aarwitz%2Ftapp?color=cb3837&label=npm)](https://www.npmjs.com/package/@aarwitz/tapp)
@@ -9,29 +9,24 @@
 [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_MCP-000000)](cursor://anysphere.cursor-deeplink/mcp/install?name=tapp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBhYXJ3aXR6L3RhcHBAbGF0ZXN0IiwibWNwIl19)
 [![VS Code MCP](https://img.shields.io/badge/VS_Code-Install_MCP-0098FF)](https://insiders.vscode.dev/redirect/mcp/install?name=tapp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40aarwitz%2Ftapp%40latest%22%2C%22mcp%22%5D%7D)
 
-**Tapp is the release-contract and evidence layer for teams shipping agent-authored applications.**
-It turns a repository and real product into an observed UI Map, a compact reviewed deterministic
-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 **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 observe-and-gate engine:
-
-- **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 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 gate.
+**Tapp gives coding agents hands and eyes on real iOS, Android, and web apps.** It can inspect and
+drive screens, explore for technical failures, save journeys as deterministic tests, and gate
+reviewed behavior in CI.
+
+Exploration reports findings, coverage, evidence, and limits. Only the repository-connected gate
+returns `pass`, `fail`, or `inconclusive`. Tapp does not turn an autonomous crawl into a subjective
+"ship-ready" score.
+
+Supported targets:
+
+| Target app | Runtime |
+|---|---|
+| iOS | Simulator on macOS with Xcode; driven through XCUITest and accessibility |
+| Android | Connected emulator or device with `adb`; driven through UIAutomator |
+| Web (beta) | Owned browser app in Playwright Chromium |
+
+Windows can host Android and web testing when their prerequisites are installed. Windows desktop
+UI applications such as WinForms, WPF, and WinUI are not currently Tapp targets.
 
 ## Give Tapp to your coding agent
 
@@ -41,38 +36,41 @@ After setup, the whole user prompt is:
 
 The official skill teaches the agent to choose the smallest useful operation, handle repositories
 with multiple app targets, inspect visual evidence, and keep exploration observations separate from
-release judgment.
+gate decisions.
 
-**Claude Code — skill and MCP tools together:**
+**Claude Code, Codex, Cursor, Copilot, and other Agent Skills clients (recommended):**
 
 ```bash
-claude plugin marketplace add aarwitz/tapp
-claude plugin install tapp@tapp
+npx -y skills add aarwitz/tapp --skill tapp
 ```
 
-Restart Claude Code after installation, open the application repository, and use the short prompt
-above. The plugin installs the `tapp` Agent Skill and launches the matching version of Tapp's stdio
-MCP server through npm; no additional prompt block, MCP configuration, or bundle id is required.
+This installs the open Agent Skills workflow into the current project and lets the agent run the npm
+CLI directly; no MCP server, plugin, account, API key, global Tapp install, or pasted prompt block is
+required. Add `-g` for a user-wide install, or `--agent claude-code`, `--agent codex`, and similar
+selectors to constrain the clients. Start or restart the agent from the application repository and
+use the short prompt above.
 
-**Claude, Codex, Cursor, Copilot, and other Agent Skills clients — skill only:**
+**Claude Code — optional enhanced skill and MCP tools:**
 
 ```bash
-npx -y skills add aarwitz/tapp --skill tapp
+claude plugin marketplace add aarwitz/tapp
+claude plugin install tapp@tapp
 ```
 
-This installs the open Agent Skills version of the same instructions into the current project and
-lets the agent fall back to the npm CLI when MCP is not connected. Add `-g` for a user-wide install,
-or `--agent claude-code`, `--agent codex`, and similar selectors to constrain the clients.
+The plugin bundles the same `tapp` Agent Skill with the matching npm-backed MCP server. Use it when
+you want inline screenshot tool results and a persistent interactive tap/read/type session; it is
+not required for the core skill-to-CLI workflow.
 
-**No agent integration:** run the npm package directly from an app repository:
+**No agent integration:** run the npm package directly from an app repository in one line:
 
 ```bash
 npx -y @aarwitz/tapp@latest init . --explore
 ```
 
 **VS Code:** install [Tapp from the Marketplace](https://marketplace.visualstudio.com/items?itemName=lidi-solutions.tapp).
-It contributes the same cross-platform Agent Skill to Copilot plus focused iOS simulator tools and a
-live simulator panel. Android and web remain available through the skill's CLI/MCP workflow.
+It contributes the same cross-platform Agent Skill to Copilot plus focused iOS simulator tools and
+an auto-refreshing screenshot preview. The preview is not an embedded Simulator or video stream.
+Android and web remain available through the skill's CLI/MCP workflow.
 
 ```
 you:    "Add a logout button to the settings screen"
@@ -96,7 +94,9 @@ npx -y @aarwitz/tapp@latest explore     # explores the real app; prints findings
 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, 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.
+report. No Tapp server, account, global install, API key, or bundle id is required for this loop.
+The platform runtime still needs to be installed, and repository onboarding can write reviewed
+configuration under `.tapp/`.
 
 The product, executable, and package leaf are all Tapp: npm distributes it as
 `@aarwitz/tapp`, while the installed command remains `tapp`.
@@ -171,18 +171,24 @@ npx -y @aarwitz/tapp@latest explore path/to/app-debug.apk --platform android --a
 npx -y @aarwitz/tapp@latest open com.acme.app --platform android
 ```
 
+Turn a driven journey into a deterministic test, or print the complete Flow format before writing
+one by hand:
+
+```bash
+npx -y @aarwitz/tapp@latest flow example
+npx -y @aarwitz/tapp@latest flow validate .tapp/flows/smoke.yml
+npx -y @aarwitz/tapp@latest flow run .tapp/flows/smoke.yml
+```
+
+Flows support an atomic `login` step using `$TEST_EMAIL` / `$TEST_PASSWORD`; Tapp's session recorder
+creates that step without writing credential values into the repository.
+
 Optional but recommended (prebuilds the test harness so the first run is fast):
 ```bash
 npx -y @aarwitz/tapp@latest install    # ~2 min, one time
 npx -y @aarwitz/tapp@latest doctor     # verify Xcode / simulators / toolchain
 ```
 
-### Optional browser workspace
-
-`npx -y @aarwitz/tapp@latest 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`/`explore` workflow.
-
 ### MCP hookup (optional)
 
 The MCP server adds the two things a CLI can't do: **screenshots inline in your agent's
@@ -387,12 +393,6 @@ environment. Add
 [`docs/scenarios.md`](docs/scenarios.md). Automatic
 baselines are isolated by platform and target, so two same-platform apps are never compared.
 
-**The hosted service is under development and is not currently offered for customer repositories.**
-Do not upload private code or credentials to an old preview. The retained
-cloud prototype is not the production SaaS boundary. Use the local Release Studio and the portable
-GitHub Action in infrastructure you control until the new account, tenant authorization, private
-evidence, and isolated-worker boundary passes security review.
-
 ## Make your repo agent-verified
 
 Drop this into your repo's `AGENTS.md` (read by Codex, Cursor, Copilot, Devin, Zed, …) so
@@ -435,13 +435,6 @@ only an optional authoring/enrichment layer (`tapp_flow_generate`, `assert_ai`,
 The first tool call builds the harness once (~2 min, cached in `~/.tapp`; rebuilt automatically
 if you switch simulators). All captures land in `~/.tapp/captures/`.
 
-## Desktop status
-
-The macOS cockpit is frozen as a supported native interface and parity floor; it still reads the
-canonical Application Model, release plan, and UI Map in Coverage. Its older import/build path is
-not yet a thin client of the shared product-operation layer, so new product work is converging in
-the browser without deleting or reducing the desktop experience.
-
 ## License
 
 [MIT](./LICENSE)

package/bin/tapp.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// tapp CLI — ship with proof.
+// Tapp CLI — agent-driven app testing on real app surfaces.
 //
 //   Zero-config verbs (the same engine the MCP tools use, exported by mcp-server/src/index.js):
 //   tapp explore <bundleId|appId|url> Autonomous exploration → findings + evidence (observation)
@@ -53,6 +53,19 @@ function bad(label, detail = "") {
   console.log(`  ❌ ${label}${detail ? ` — ${detail}` : ""}`);
 }
 
+let lastProgressLine = "";
+function writeProgress(line) {
+  const text = String(line || "").trimEnd();
+  if (process.stderr.isTTY) process.stderr.write(`\r${text}   `);
+  else if (text && text !== lastProgressLine) console.error(text);
+  lastProgressLine = text;
+}
+
+function finishProgress() {
+  if (process.stderr.isTTY && lastProgressLine) process.stderr.write("\n");
+  lastProgressLine = "";
+}
+
 function bootedSims() {
   const r = run("xcrun", ["simctl", "list", "devices", "booted", "-j"]);
   if (r.code !== 0) return [];
@@ -155,7 +168,7 @@ const engineImport = () => import(path.join(packageRoot, "mcp-server", "src", "i
 
 function requireMacFor(what) {
   if (process.platform === "darwin") return;
-  console.error(`❌ ${what} requires macOS (Xcode + iOS simulator). The web beta runs anywhere: tapp explore https://localhost:3000`);
+  console.error(`❌ ${what} requires macOS (Xcode + iOS simulator). The web beta runs anywhere: npx -y @aarwitz/tapp@latest explore https://localhost:3000`);
   process.exit(1);
 }
 
@@ -247,7 +260,7 @@ function safeCommandUsage(verb) {
     shot: "tapp shot [--out FILE]",
     apps: "tapp apps",
     build: "tapp build [repo] [--scheme NAME] [--configuration NAME]",
-    flow: "tapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--email VALUE] [--password VALUE]",
+    flow: "tapp flow example\ntapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--email VALUE] [--password VALUE]",
     task: "tapp task validate FILE [--platform PLATFORM] [--map FILE]\ntapp task compile FILE --platform PLATFORM [--inputs JSON] [--out FILE]\ntapp task run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID] [--inputs JSON]",
     contract: "tapp contract validate FILE [--platform PLATFORM] [--map FILE]\ntapp contract compile FILE --platform PLATFORM [--out FILE]\ntapp contract run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID]",
     scenario: "tapp scenario validate FILE [--project-dir DIR]\ntapp scenario run FILE --platform web --url URL [--project-dir DIR]",
@@ -279,9 +292,8 @@ const safeHelpRequested = (rest.includes("--help") || rest.includes("-h"))
   && !["help", "version", "--version", "-v"].includes(command)
   && (command !== "ci" || rest[0] === "install");
 if (safeHelpRequested) {
-  console.log(`Usage:\n  ${safeCommandUsage(command).replaceAll("\n", "\n  ")}\n\nℹ️  --help never builds, launches, writes, or opens. Full command reference:\n`);
-  command = "help";
-  rest = [];
+  console.log(`Usage:\n  ${safeCommandUsage(command).replaceAll("\n", "\n  ")}\n\nℹ️  --help never builds, launches, writes, or opens. Run \`tapp --help\` for the full command reference.`);
+  process.exit(0);
 }
 
 // Create TAPP_HOME only for commands that actually use it — never for help/version/--help.
@@ -350,7 +362,7 @@ switch (command) {
       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"}   `);
+        writeProgress(`🔍 Import exploration… ${progress.action}/${progress.max || actions} actions · ${progress.states} ${activePlatform === "web" ? "pages reached" : activePlatform === "ios" ? "structural states observed" : "screens reached"}`);
       },
       onStatus: (status) => console.error(`⏳ ${status}`),
       outDir,
@@ -377,11 +389,11 @@ switch (command) {
       }
     }
     if (failure) {
-      if (explore) process.stderr.write("\n");
+      if (explore) finishProgress();
       printEngineError({ error: `Could not initialize repository: ${failure.message || String(failure)}`, details: failure.details || {} });
       process.exit(2);
     }
-    if (explore) process.stderr.write("\n");
+    if (explore) finishProgress();
     const built = { model: result.model, plan: result.plan };
     const written = result.written;
     const exploration = result.exploration;
@@ -547,7 +559,7 @@ switch (command) {
         const modelPlatform = typeof flags.platform === "string" ? flags.platform.toLowerCase() : "";
         if (modelPlatform === "ios") requireMacFor("iOS testing");
         const onProgress = (p) =>
-          process.stderr.write(`\r🔍 Exploring… ${p.action}/${p.max || flags.actions || 60} actions · ${p.states} states observed   `);
+          writeProgress(`🔍 Exploring… ${p.action}/${p.max || flags.actions || 60} actions · ${p.states} states observed`);
         const r = await engine.runExploreTarget({
           projectDir: process.cwd(),
           platform: modelPlatform,
@@ -563,7 +575,7 @@ switch (command) {
           onProgress,
           onStatus: (t) => console.error(`ℹ️  ${t}`),
         });
-        process.stderr.write("\n");
+        finishProgress();
         if (r.error) { printEngineError(r); process.exit(1); }
         console.log(r.text);
         if (flags.json && typeof flags.json === "string") {
@@ -588,14 +600,14 @@ switch (command) {
       process.exit(2);
     }
     if (platform === "web" && !/^https?:\/\//i.test(target)) {
-      console.error("❌ Web QA needs an http(s) URL");
+      console.error("❌ Web exploration needs an http(s) URL");
       process.exit(2);
     }
     const bundleId = platform === "ios" ? await resolveTargetOrExit(engine, target) : null;
     const android = platform === "android" ? androidTarget(flags, target) : null;
     const progressMetric = platform === "web" ? "pages reached" : platform === "ios" ? "structural states observed" : "screens reached";
     const onProgress = (p) =>
-      process.stderr.write(`\r🔍 Exploring… ${p.action}/${p.max || flags.actions || 60} actions · ${p.states} ${progressMetric}   `);
+      writeProgress(`🔍 Exploring… ${p.action}/${p.max || flags.actions || 60} actions · ${p.states} ${progressMetric}`);
     const r = platform === "web"
       ? await engine.runQaWeb({
           url: target,
@@ -628,7 +640,7 @@ switch (command) {
           surface: "cli",
           onProgress,
         });
-    process.stderr.write("\n");
+    finishProgress();
     if (r.error) {
       printEngineError(r);
       process.exit(1);
@@ -839,8 +851,22 @@ switch (command) {
       printEngineError(inst);
       process.exit(1);
     }
+    let modelRefresh = null;
+    try {
+      const { persistIosBuildValidation } = await import(path.join(packageRoot, "mcp-server", "src", "application-model.js"));
+      modelRefresh = await persistIosBuildValidation({
+        projectDir: dir,
+        bundleId: inst.bundleId,
+        container: built.container,
+        scheme: built.scheme,
+        configuration: built.configuration,
+      });
+    } catch (error) {
+      console.error(`⚠️  Build succeeded, but Tapp could not refresh the existing application model: ${error.message || String(error)}`);
+    }
     console.log(`🔨 Built ${path.basename(built.appPath)} (scheme ${built.scheme}) — installed as ${inst.bundleId}`);
-    console.log(`\nNext: tapp explore ${inst.bundleId}`);
+    if (modelRefresh) console.log(`   application model refreshed: ${modelRefresh.modelPath}`);
+    console.log(`\nNext: npx -y @aarwitz/tapp@latest explore ${inst.bundleId}`);
     break;
   }
 
@@ -923,8 +949,12 @@ switch (command) {
     const { flags, positionals } = parseVerbArgs(rest);
     const verb = positionals[0] || "run";
     const flowPath = positionals[1] || (verb === "run" || verb === "validate" ? "" : verb);
+    if (verb === "example") {
+      console.log(`# Tapp Flow — deterministic, keyless replay\nname: sign-in-smoke\nplatform: web\nurl: https://example.test/login\nsteps:\n  - login:\n      email: $TEST_EMAIL\n      password: $TEST_PASSWORD\n  - wait_for: Dashboard\n  - assert_screen: Dashboard\n`);
+      break;
+    }
     if (!["run", "validate"].includes(verb) || !flowPath) {
-      console.error("usage: tapp flow run <flow.yml> [--platform ios|android|web] [--url URL] [--app-id ID] [--apk FILE] [--serial ID]\n       tapp flow validate <flow.yml>");
+      console.error("usage: tapp flow example\n       tapp flow run <flow.yml> [--platform ios|android|web] [--url URL] [--app-id ID] [--apk FILE] [--serial ID]\n       tapp flow validate <flow.yml>");
       process.exit(2);
     }
     const absolute = path.resolve(flowPath);
@@ -1054,7 +1084,7 @@ switch (command) {
       try {
         const adopted = adoptPrCoverageProposal({ projectDir, prPlanPath, item: flags.item, releasePlanPath: typeof flags["release-plan"] === "string" ? flags["release-plan"] : undefined });
         console.log(`📥 ${adopted.mode === "reconciled-existing" ? "Reconciled PR evidence into" : "Adopted"} ${adopted.item.name}${adopted.mode === "reconciled-existing" ? ` while preserving decision '${adopted.item.decision}'` : " as a pending release-plan item"}; no Task or contract was generated or trusted`);
-        console.log(`   plan: ${adopted.path}\n   next: tapp plan review ${adopted.path} --approve ${adopted.item.id}`);
+        console.log(`   plan: ${adopted.path}\n   next: npx -y @aarwitz/tapp@latest plan review ${adopted.path} --approve ${adopted.item.id}`);
       } catch (error) { console.error(`❌ Could not adopt PR coverage proposal: ${error.message || String(error)}`); process.exit(2); }
       break;
     }
@@ -1214,6 +1244,13 @@ switch (command) {
     const python = run("python3", ["--version"]);
     python.code === 0 ? ok("python3", `${python.stdout} (used by Flows)`) : bad("python3", "not found — Flow replay needs python3 + pyyaml (everything else works)");
 
+    const { storagePreflight } = await import(path.join(packageRoot, "mcp-server", "src", "environment-preflight.js"));
+    const storage = storagePreflight(tappHome);
+    if (storage.level === "blocked") { bad("Disk space", storage.message); healthy = false; }
+    else if (storage.level === "warning") console.log(`  ⚠️  Disk space — ${storage.message}`);
+    else if (storage.level === "ok") ok("Disk space", storage.message);
+    else console.log(`  ⬜ Disk space — ${storage.message || "could not be checked"}`);
+
     console.log("\n  Platforms:");
     if (process.platform === "darwin") {
       const xcode = run("xcode-select", ["-p"]);
@@ -1223,7 +1260,7 @@ switch (command) {
         const booted = bootedSims();
         ok("iOS", `${ver || "Xcode"}; ${booted.length ? `${booted[0].name} booted` : "no simulator booted yet"}`);
         const xctestrun = harnessXctestrun();
-        xctestrun ? ok("iOS harness cache", xctestrun) : console.log("  ⬜ iOS harness cache — builds on first use (or: tapp install)");
+        xctestrun ? ok("iOS harness cache", xctestrun) : console.log("  ⬜ iOS harness cache — builds on first use (or: npx -y @aarwitz/tapp@latest install)");
       } else {
         console.log("  ⬜ iOS — unavailable (install Xcode + simulator runtime)");
       }
@@ -1257,7 +1294,7 @@ switch (command) {
     console.log(`\n  Home: ${tappHome}`);
     console.log(healthy
       ? "\nReady. Start with:\n  npx -y @aarwitz/tapp@latest open [target]\n  npx -y @aarwitz/tapp@latest explore [target]"
-      : "\nFix the ❌ items above, then re-run: tapp doctor");
+      : "\nFix the ❌ items above, then re-run: npx -y @aarwitz/tapp@latest doctor");
     process.exit(healthy ? 0 : 1);
   }
 
@@ -1332,7 +1369,13 @@ switch (command) {
       console.log(`✅ Actor '${name}' configured — ${result.actor.session} session · ${result.actor.provisioning} provisioning`);
       console.log(`   ${result.path}`);
       console.log(`   bindings: ${Object.entries(result.actor.credentials).map(([key, binding]) => `${key}=$${binding.env}`).join(", ") || "none"}`);
-      console.log("   No credential values were accepted or written. Rerun tapp init --refresh to update the application model.");
+      const { refreshExistingInitArtifacts } = await import(path.join(packageRoot, "mcp-server", "src", "application-model.js"));
+      let refreshed = null;
+      let refreshWarning = "";
+      try { refreshed = await refreshExistingInitArtifacts({ projectDir }); }
+      catch (error) { refreshWarning = error.message || String(error); }
+      console.log(`   No credential values were accepted or written.${refreshed ? ` Application model refreshed: ${refreshed.modelPath}` : " Run npx -y @aarwitz/tapp@latest init when you are ready to create the application model."}`);
+      if (refreshWarning) console.error(`⚠️  Actor was saved, but Tapp could not refresh the existing application model: ${refreshWarning}`);
     } catch (error) { console.error(`❌ Actor not configured: ${error.message || String(error)}`); process.exit(2); }
     break;
   }
@@ -1347,7 +1390,7 @@ switch (command) {
     const projectDir = fs.realpathSync(path.resolve(positionals[1] || (typeof flags["project-dir"] === "string" ? flags["project-dir"] : process.cwd())));
     const modelPath = typeof flags.model === "string" ? path.resolve(projectDir, flags.model) : existingProjectArtifactPath(projectDir, "application-model.json");
     if (!modelPath.startsWith(projectDir + path.sep) || !fs.existsSync(modelPath)) {
-      console.error(`❌ Application model not found inside the repository: ${modelPath}\n   Run tapp init --explore, review/generate/validate/promote the plan, then create the baseline.`);
+      console.error(`❌ Application model not found inside the repository: ${modelPath}\n   Run npx -y @aarwitz/tapp@latest init --explore, review/generate/validate/promote the plan, then create the baseline.`);
       process.exit(2);
     }
     let model;
@@ -1454,7 +1497,7 @@ switch (command) {
       catch { console.error(`❌ Repository directory not found: ${positionals[0] || flags["project-dir"] || process.cwd()}`); process.exit(2); }
       const modelPath = typeof flags.model === "string" ? path.resolve(projectDir, flags.model) : existingProjectArtifactPath(projectDir, "application-model.json");
       if (!modelPath.startsWith(projectDir + path.sep) || !fs.existsSync(modelPath)) {
-        console.error(`❌ Application model not found inside the repository: ${modelPath}\n   Run tapp init --explore first.`);
+        console.error(`❌ Application model not found inside the repository: ${modelPath}\n   Run npx -y @aarwitz/tapp@latest init --explore first.`);
         process.exit(2);
       }
       const actionRef = typeof flags["action-ref"] === "string" ? flags["action-ref"] : `aarwitz/tapp@v${pkg.version}`;
@@ -1571,17 +1614,17 @@ switch (command) {
   }
 
   default: {
-    console.log(`tapp v${pkg.version} — ship with proof. Autonomous exploration and deterministic release gates for iOS, Android, and web.
+    console.log(`tapp v${pkg.version} — agent-driven app testing for iOS, Android, and web.
 
-Core — explore, prove, gate (agents and humans can just run these — no server, no setup):
+Core — inspect, explore, gate (no Tapp account or server required):
   tapp explore [target]    Autonomous exploration → findings + evidence (an observation, NOT a
-                           release decision — run 'tapp ci' to gate a merge)
+                           release decision — run 'npx -y @aarwitz/tapp@latest ci' to gate a merge)
                            (web: --watch · all: --platform ios|android|web · --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):
+Primitives — an agent's eyes and hands:
   tapp open [target]       Launch the app → screen summary + screenshot saved to a file
                            (web: --tap TEXT · --wait-for TEXT · --out FILE)
   tapp tree [target]       Accessibility tree of the current screen (--json for every element)
@@ -1597,6 +1640,7 @@ Repository & release:
   tapp actor list [repo]   Inspect named actors, sessions, provisioning, and secret env bindings
 
 Advanced — deterministic suites, lifecycle & compilers:
+  tapp flow example        Print a complete starter Flow YAML (no target or MCP required)
   tapp flow run FILE       Replay a committed deterministic Flow (no AI/API key)
   tapp flow validate FILE  Validate a Flow without launching a target
   tapp task validate FILE  Validate a reusable deterministic Task (+ optional UI Map grounding)
@@ -1636,7 +1680,7 @@ Setup:
   tapp doctor     Check Xcode / simulators / toolchain
   tapp mcp        Start the MCP server on stdio (adds inline screenshots + interactive sessions)
 
-Agent Skill (optional — so a short “Use Tapp to test this app” prompt is enough):
+Agent Skill (recommended — so a short “Use Tapp to test this app” prompt is enough):
   Any supported agent: npx -y skills add aarwitz/tapp --skill tapp
   Claude skill + MCP:  claude plugin marketplace add aarwitz/tapp
                        claude plugin install tapp@tapp

package/mcp-server/src/android-explorer.js

@@ -74,6 +74,7 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
   const visited = new Map();
   let issues = 0;
   let actions = 0;
+  let loginTried = false;
   const crashExitBaseline = typeof d.latestCrashExitInfo === "function" ? await d.latestCrashExitInfo() : null;
   let snap = await d.launch({ clearData });
   let crashReported = false;
@@ -210,6 +211,7 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
     if (candidate) {
       const target = controlLabel(candidate);
       const loginSubmit = inputs.some((input) => input.secure) && isAndroidAuthSubmit(candidate);
+      if (loginSubmit) loginTried = true;
       tried.add(`${hash}|tap|${target}`);
       const before = hash;
       const r = await d.tap(target, snap);
@@ -260,7 +262,7 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
   }
 
   const timedOut = Date.now() >= deadline;
-  emit("COMPLETE", { actions, states: visited.size, issues, screens: [...new Set(visited.values())].join(","), outcome: timedOut ? "timeout" : "complete", timedOut, ...(timedOut ? { timeoutSeconds: timeoutSec } : {}) });
+  emit("COMPLETE", { actions, states: visited.size, issues, screens: [...new Set(visited.values())].join(","), outcome: timedOut ? "timeout" : "complete", timedOut, credentialsProvided: !!(testEmail || testPassword), credentialsUsed: loginTried, ...(timedOut ? { timeoutSeconds: timeoutSec } : {}) });
   onProgress({ action: actions, max: maxActions, states: visited.size });
   return { markersPath, outDir, actions, states: visited.size, issues, timedOut, seedTargets: normalizedTargets };
 }