@aarwitz/tapp 0.17.0-rc.9 → 0.17.1

package/README.md

@@ -1,59 +1,110 @@
-# 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 lets coding agents verify UI changes on real iOS, Android, and web surfaces, then turns
+reviewed proof into deterministic CI checks.** It can inspect and drive screens, explore for
+technical failures, and save important journeys as replayable tests.
+
+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. Inspecting, focused evidence, autonomous exploration, deterministic replay, and gating
+need no MCP server, plugin, account, API key, global Tapp install, or pasted prompt block. 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. Add it when
+you want inline screenshot results or when the agent must interactively tap, type, and record an
+arbitrary multi-step journey in one persistent 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"
 agent:  *writes the Swift*
-agent:  *tapp: builds, opens the app, navigates to Settings, screenshots it*
+agent:  *tapp: finds Settings in source, follows its previously observed route, 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.
 
-From the app repository, let the agent see the current screen and then explore it:
+From the app repository, ground Tapp once, then use the smallest operation for later checks:
 
 ```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 init . --explore # first run: detect/build, explore, and ground .tapp/ui-map.json
+npx -y @aarwitz/tapp@latest open            # one current screen + screenshot
+npx -y @aarwitz/tapp@latest focus "Save storefront settings visible above keyboard" # source + observed-route fast path
+npx -y @aarwitz/tapp@latest explore         # later broad exploration (observation, not a gate)
 ```
 
+Source tells `focus` where the requested UI likely lives; only a route already observed in
+`.tapp/ui-map.json` authorizes navigation. If a fresh repository has no such route yet, Tapp returns
+the source evidence instead of guessing through the app.
+
 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 +113,36 @@ 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 .
 ```
 
+Actor setup refuses to overwrite an existing actor. Repeat `actor set` with `--replace` only when
+you intend to replace that actor's reviewed role, session, provisioning, or credential bindings.
+
+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 +155,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 +208,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 +224,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 +256,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
@@ -264,7 +337,7 @@ jobs:
     timeout-minutes: 45
     steps:
       - uses: actions/checkout@v4
-      - uses: aarwitz/tapp@main # pin to the newest release tag for production
+      - uses: aarwitz/tapp@v0.17.1 # or pin the reviewed release commit SHA
         with:
           project: MyApp.xcodeproj # or MyApp.xcworkspace
           scheme: MyApp
@@ -297,7 +370,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 \
@@ -314,7 +387,7 @@ Android CI runs on Linux with an emulator/device already connected. The Action c
 or accept a prebuilt one:
 
 ```yaml
-- uses: aarwitz/tapp@main
+- uses: aarwitz/tapp@v0.17.1 # or pin the reviewed release commit SHA
   with:
     platform: android
     android-app-id: com.acme.app
@@ -331,12 +404,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 +412,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 +446,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)