@aarwitz/tapp 0.17.0-rc.8 → 0.17.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,34 @@
+{
+  "name": "tapp",
+  "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"
+  },
+  "plugins": [
+    {
+      "name": "tapp",
+      "source": {
+        "source": "npm",
+        "package": "@aarwitz/tapp"
+      },
+      "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://runtapp.com/",
+      "license": "MIT",
+      "keywords": [
+        "ios",
+        "simulator",
+        "testing",
+        "qa",
+        "xcuitest",
+        "mcp",
+        "agent-skill",
+        "copilot"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,33 @@
+{
+  "name": "tapp",
+  "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",
+  "author": {
+    "name": "Aaron Horowitz",
+    "url": "https://github.com/aarwitz"
+  },
+  "homepage": "https://runtapp.com/",
+  "repository": "https://github.com/aarwitz/tapp",
+  "license": "MIT",
+  "keywords": [
+    "ios",
+    "simulator",
+    "testing",
+    "qa",
+    "xcuitest",
+    "mcp",
+    "agent-skill",
+    "copilot"
+  ],
+  "mcpServers": {
+    "tapp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@aarwitz/tapp@0.17.0",
+        "mcp"
+      ],
+      "cwd": "${CLAUDE_PROJECT_DIR}"
+    }
+  }
+}

package/AGENTS.md

@@ -1,26 +1,40 @@
 # 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.
 
 ```bash
-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 explore app.apk --platform android --app-id com.acme.app
-npx -y @aarwitz/tapp flow run .tapp/flows/smoke.yml  # committed, keyless E2E replay
+npx -y @aarwitz/tapp@latest explore [target]     # autonomous exploration → findings + evidence (observation, not a gate; ≈ tapp_explore)
+npx -y @aarwitz/tapp@latest explore https://your-app.example --watch  # web: visibly follow the same exploration
+npx -y @aarwitz/tapp@latest open [target]   # launch + screen summary + screenshot saved to a file (≈ tapp_open_app)
+npx -y @aarwitz/tapp@latest tree [target]   # accessibility tree, --json for every element (≈ tapp_ui_tree)
+npx -y @aarwitz/tapp@latest shot            # screenshot the booted sim → file path (≈ tapp_screenshot)
+npx -y @aarwitz/tapp@latest apps            # what's installed on the simulator, with bundle ids
+npx -y @aarwitz/tapp@latest build [dir]     # build the app in an Xcode repo + install it (≈ tapp_build)
+npx -y @aarwitz/tapp@latest explore app.apk --platform android --app-id com.acme.app
+npx -y @aarwitz/tapp@latest flow run .tapp/flows/smoke.yml  # committed, keyless E2E replay
 ```
 
+If repository onboarding detects multiple application targets, target detection is deterministic but
+the choice is the user's. Explicit `init --explore` asks even when the model has a saved default; a
+later bare `explore` may consume that default. In a human TTY, Tapp displays a numbered selector and
+continues in the same command. A non-interactive CLI prints the exact choices and exits before
+building. MCP returns
+`reason: "target-selection-required"` with structured `choices[]` (`platform`, `name`, `sourcePath`,
+`selector`, and exact `command`). **Do not pick one yourself.** Present those choices to the user
+with the client's native multiple-choice question UI when available, then rerun using the selected
+`--platform` and `--target`. Plain chat can list the same choices when the client has no question
+widget.
+
 For focused web evidence, `open` and `tree` accept one semantic interaction plus an async content
 wait: `tapp open https://example.com --tap "Not now" --wait-for "Dashboard"`. Tapp waits for the
 page to stabilize before capturing it and warns honestly if the bounded wait ends while it is still
@@ -32,7 +46,9 @@ that IS the screen. If you cannot (Cursor, VS Code Copilot), connect the MCP ser
 instead: its tool results carry the screenshot inline. Screen *recordings* are for the
 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.
+watch it. On **web**, explicit `--watch` opens the isolated Playwright Chromium window and overlays
+Tapp's current action and pointer; the overlay is omitted from evidence screenshots. It does not
+drive the person's existing/default browser profile.
 
 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
@@ -43,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 |
@@ -53,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" }
@@ -76,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.
@@ -120,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,35 +1,76 @@
-# 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)
 [![npm downloads](https://img.shields.io/npm/dw/%40aarwitz%2Ftapp?label=downloads)](https://www.npmjs.com/package/@aarwitz/tapp)
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
-[![Install in Cursor](https://img.shields.io/badge/Cursor-Install_MCP-000000)](cursor://anysphere.cursor-deeplink/mcp/install?name=tapp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBhYXJ3aXR6L3RhcHAiLCJtY3AiXX0=)
-[![Install in VS Code](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%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.
+[![Agent Skill](https://img.shields.io/badge/Agent_Skill-install-6b5cff)](https://skills.sh/aarwitz/tapp)
+[![VS Code extension](https://img.shields.io/badge/VS_Code-extension-0098FF)](https://marketplace.visualstudio.com/items?itemName=lidi-solutions.tapp)
+[![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 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
+
+After setup, the whole user prompt is:
+
+> Use Tapp to test this app.
+
+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
+gate decisions.
+
+**Claude Code, Codex, Cursor, Copilot, and other Agent Skills clients (recommended):**
+
+```bash
+npx -y skills add aarwitz/tapp --skill tapp
+```
+
+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 Code — optional enhanced skill and MCP tools:**
+
+```bash
+claude plugin marketplace add aarwitz/tapp
+claude plugin install tapp@tapp
+```
+
+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 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
+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"
@@ -38,7 +79,7 @@ agent:  *tapp: builds, opens the app, navigates to Settings, screenshots it*
 agent:  "Done — and here it is working on the simulator: [screenshot]"
 ```
 
-## Quickstart for coding agents
+## npm CLI quickstart
 
 Requirements: **Node ≥ 18**. iOS needs **macOS + Xcode**; Android needs `adb` plus a connected
 emulator/device; web needs Playwright + Chromium.
@@ -46,14 +87,16 @@ emulator/device; web needs Playwright + Chromium.
 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 explore     # explores the real app; prints findings + evidence (an observation, not a gate)
+npx -y @aarwitz/tapp@latest open   # builds/launches as needed; prints a screenshot path + screen summary
+npx -y @aarwitz/tapp@latest 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, 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`.
@@ -62,24 +105,33 @@ To bootstrap maintained release infrastructure, preview the repository model and
 before Tapp writes anything:
 
 ```bash
-npx -y @aarwitz/tapp init . --dry-run --json-out /tmp/tapp-init.json
+npx -y @aarwitz/tapp@latest init . --dry-run --json-out /tmp/tapp-init.json
 # Build/start the detected web target, ground the first UI Map, then stop it.
-npx -y @aarwitz/tapp init . --explore --platform web
+npx -y @aarwitz/tapp@latest init . --explore --platform web
 # Or build/install the detected Xcode target, ground the map, and persist the validated scheme.
-npx -y @aarwitz/tapp init . --explore --platform ios --target .
+npx -y @aarwitz/tapp@latest init . --explore --platform ios --target .
 # Or connect to an already-running owned URL:
-npx -y @aarwitz/tapp init . --explore --platform web --url http://127.0.0.1:4173
+npx -y @aarwitz/tapp@latest init . --explore --platform web --url http://127.0.0.1:4173
 # If the app has roles/accounts, bind names once; values stay in local/CI secrets.
-npx -y @aarwitz/tapp actor set alice . --role member --session isolated \
+npx -y @aarwitz/tapp@latest actor set alice . --role member --session isolated \
   --credential email=ALICE_EMAIL --credential password=ALICE_PASSWORD
 # Review-only path: tapp init . → tapp plan show → tapp plan review --approve ...
 
 # After approved drafts replay and are promoted, establish the selected target's baseline
 # through the ordinary full gate, then generate the reviewable GitHub workflow.
-npx -y @aarwitz/tapp baseline create . --platform web
-npx -y @aarwitz/tapp ci install .
+npx -y @aarwitz/tapp@latest baseline create . --platform web
+npx -y @aarwitz/tapp@latest ci install .
 ```
 
+In a repository containing multiple apps (for example, iOS plus web),
+`tapp init . --explore` without an explicit target does not guess from detection order—even when a
+prior choice is recorded. A human terminal gets a numbered
+selector; a non-interactive CLI prints exact target-selection commands, while MCP also returns
+structured choices. Neither builds or writes before the choice. After you choose one, the model
+retains every detected target and records the choice as the default for the next bare `tapp explore`;
+explicit `init --explore` continues to ask because it is the onboarding/refresh operation. Setup gaps
+belonging only to unselected targets are shown as informational, not as failures of the selected run.
+
 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
@@ -92,42 +144,50 @@ Every verb takes whatever you have: nothing (auto-detects the repo you're in, or
 already on the simulator), a repo directory, a `path/to/App.app`, or a bundle id:
 
 ```bash
-npx -y @aarwitz/tapp open [target]   # launch the app → screen summary + screenshot file
-npx -y @aarwitz/tapp tree [target]   # accessibility tree of the current screen
-npx -y @aarwitz/tapp shot            # screenshot the booted simulator
-npx -y @aarwitz/tapp apps            # what's installed on the simulator (names + bundle ids)
-npx -y @aarwitz/tapp build [dir]     # just build + install (scheme auto-detected)
+npx -y @aarwitz/tapp@latest open [target]   # launch the app → screen summary + screenshot file
+npx -y @aarwitz/tapp@latest tree [target]   # accessibility tree of the current screen
+npx -y @aarwitz/tapp@latest shot            # screenshot the booted simulator
+npx -y @aarwitz/tapp@latest apps            # what's installed on the simulator (names + bundle ids)
+npx -y @aarwitz/tapp@latest build [dir]     # just build + install (scheme auto-detected)
 ```
 
-Web (beta): `npx -y @aarwitz/tapp explore http://localhost:3000` *(one-time setup:
-`npm i -g playwright && npx playwright install chromium`)*
+Web (beta): `npx -y @aarwitz/tapp@latest explore http://localhost:3000` *(one-time setup:
+`npm i -g playwright && npx playwright install chromium`)*. Add `--watch` to open Tapp's controlled,
+isolated Chromium window and follow its clicks with an on-page pointer/action label. Tapp hides that
+watch UI from saved evidence screenshots and does not automate your personal/default browser profile.
 
 Focused web inspection waits briefly for loading states to settle. If a consent or location modal
 blocks the screen, dismiss it and wait for the content you care about in the same package-only call:
 
 ```bash
-npx -y @aarwitz/tapp open https://example.com --tap "Not now" --wait-for "Dashboard"
-npx -y @aarwitz/tapp tree https://example.com --tap "Not now" --wait-for "Dashboard" --json
+npx -y @aarwitz/tapp@latest open https://example.com --tap "Not now" --wait-for "Dashboard"
+npx -y @aarwitz/tapp@latest tree https://example.com --tap "Not now" --wait-for "Dashboard" --json
 ```
 
 Android:
 
 ```bash
-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
+npx -y @aarwitz/tapp@latest explore path/to/app-debug.apk --platform android --app-id com.acme.app
+npx -y @aarwitz/tapp@latest open com.acme.app --platform android
 ```
 
-Optional but recommended (prebuilds the test harness so the first run is fast):
+Turn a driven journey into a deterministic test, or print the complete Flow format before writing
+one by hand:
+
 ```bash
-npx -y @aarwitz/tapp install    # ~2 min, one time
-npx -y @aarwitz/tapp doctor     # verify Xcode / simulators / toolchain
+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
 ```
 
-### Optional browser workspace
+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.
 
-`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`/`explore` workflow.
+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
+```
 
 ### MCP hookup (optional)
 
@@ -137,14 +197,14 @@ context** (the model literally sees the screen) and the **interactive session lo
 
 **Claude Code:**
 ```bash
-claude mcp add tapp -- npx -y @aarwitz/tapp mcp
+claude mcp add tapp -- npx -y @aarwitz/tapp@latest mcp
 ```
 
 **Cursor / VS Code (Copilot)** — add to `~/.cursor/mcp.json` (Cursor) or `.vscode/mcp.json` (VS Code):
 ```json
 {
   "servers": {
-    "tapp": { "type": "stdio", "command": "npx", "args": ["-y", "@aarwitz/tapp", "mcp"] }
+    "tapp": { "type": "stdio", "command": "npx", "args": ["-y", "@aarwitz/tapp@latest", "mcp"] }
   }
 }
 ```
@@ -153,10 +213,10 @@ claude mcp add tapp -- npx -y @aarwitz/tapp mcp
 ```toml
 [mcp_servers.tapp]
 command = "npx"
-args = ["-y", "@aarwitz/tapp", "mcp"]
+args = ["-y", "@aarwitz/tapp@latest", "mcp"]
 ```
 
-**Any other MCP client:** stdio command `npx -y @aarwitz/tapp mcp`.
+**Any other MCP client:** stdio command `npx -y @aarwitz/tapp@latest mcp`.
 
 Then ask your agent:
 > "Explore my app and show me what breaks."
@@ -185,7 +245,9 @@ Then ask your agent:
 | 📱 | `tapp_list_simulators` / `boot_simulator` / `install_app` | Simulator + app management. |
 | 🩺 | `tapp_health`, `tapp_capture*`, `tapp_parse_markers` | Diagnostics and capture history. |
 
-Full agent playbook: [AGENTS.md](./AGENTS.md) — ships inside the package so agents can read it too.
+Canonical installable skill: [`skills/tapp/SKILL.md`](skills/tapp/SKILL.md). Full low-level tool
+reference: [AGENTS.md](./AGENTS.md). Both ship inside the npm package; installing the Claude plugin
+or Agent Skill is what makes the workflow discoverable without pasting instructions.
 Application-model and import contract: [`docs/application-model.md`](docs/application-model.md).
 The desktop Coverage view reads the same `.tapp/application-model.json`,
 `.tapp/release-plan.json`, and `.tapp/ui-map.json`, including explicit proposal review; it
@@ -297,7 +359,7 @@ accepts that `.app`, detects its bundle id, writes report artifacts, and exits n
 gate fails:
 
 ```bash
-npx -y @aarwitz/tapp ci --app path/to/MyApp.app \
+npx -y @aarwitz/tapp@latest ci --app path/to/MyApp.app \
   --project-dir . --pr-base origin/main --pr-head HEAD \
   --target-key target_ios_myapp \
   --pr-plan-out tapp-pr-plan.json \
@@ -331,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
@@ -345,9 +401,9 @@ your agent proves its UI work instead of claiming it:
 ```markdown
 ## Verifying UI changes
 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
+(iOS simulator, Android emulator/device, or a browser for web). After any UI change, run `npx -y @aarwitz/tapp@latest 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 explore` (or `explore <url>` for web)
+proof. Before declaring a feature done, run `npx -y @aarwitz/tapp@latest 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_explore.)
@@ -379,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)