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

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "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.12",
+  "version": "0.17.0-rc.13",
   "author": {
     "name": "Aaron Horowitz",
     "url": "https://github.com/aarwitz"
@@ -21,9 +21,10 @@
   ],
   "mcpServers": {
     "tapp": {
-      "command": "node",
+      "command": "npx",
       "args": [
-        "${CLAUDE_PLUGIN_ROOT}/bin/tapp.js",
+        "-y",
+        "@aarwitz/tapp@0.17.0-rc.13",
         "mcp"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}"

package/AGENTS.md

@@ -11,15 +11,15 @@ the app already on the simulator); it also accepts a repo dir, a `path/to/App.ap
 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 explore https://your-app.example --watch  # web: visibly follow the same exploration
-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

package/README.md

@@ -6,8 +6,8 @@
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 [![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=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBhYXJ3aXR6L3RhcHAiLCJtY3AiXX0=)
-[![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%22%2C%22mcp%22%5D%7D)
+[![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
@@ -51,8 +51,8 @@ claude plugin install tapp@tapp
 ```
 
 Restart Claude Code after installation, open the application repository, and use the short prompt
-above. The plugin bundles both the `tapp` Agent Skill and the local stdio MCP server; no additional
-prompt block or bundle id is required.
+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.
 
 **Claude, Codex, Cursor, Copilot, and other Agent Skills clients — skill only:**
 
@@ -67,7 +67,7 @@ or `--agent claude-code`, `--agent codex`, and similar selectors to constrain th
 **No agent integration:** run the npm package directly from an app repository:
 
 ```bash
-npx -y @aarwitz/tapp init . --explore
+npx -y @aarwitz/tapp@latest init . --explore
 ```
 
 **VS Code:** install [Tapp from the Marketplace](https://marketplace.visualstudio.com/items?itemName=lidi-solutions.tapp).
@@ -89,8 +89,8 @@ 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
@@ -105,22 +105,22 @@ 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),
@@ -144,14 +144,14 @@ 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:
+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.
@@ -160,26 +160,26 @@ Focused web inspection waits briefly for loading states to settle. If a consent
 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):
 ```bash
-npx -y @aarwitz/tapp install    # ~2 min, one time
-npx -y @aarwitz/tapp doctor     # verify Xcode / simulators / toolchain
+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 app .` opens a local Release Studio for people who want visual repository
+`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.
 
@@ -191,14 +191,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"] }
   }
 }
 ```
@@ -207,10 +207,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."
@@ -353,7 +353,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 \
@@ -401,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.)

package/bin/tapp.js

@@ -1256,7 +1256,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 explore [target]"
+      ? "\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");
     process.exit(healthy ? 0 : 1);
   }
@@ -1642,9 +1642,9 @@ Agent Skill (optional — so a short “Use Tapp to test this app” prompt is e
                        claude plugin install tapp@tapp
 
 MCP hookup (optional — for inline screenshots and the tap/type/inspect session loop):
-  Claude Code:   claude mcp add tapp -- npx -y @aarwitz/tapp mcp
+  Claude Code:   claude mcp add tapp -- npx -y @aarwitz/tapp@latest mcp
   Cursor/VS Code (mcp.json):
-    { "servers": { "tapp": { "type": "stdio", "command": "npx", "args": ["-y", "@aarwitz/tapp", "mcp"] } } }
+    { "servers": { "tapp": { "type": "stdio", "command": "npx", "args": ["-y", "@aarwitz/tapp@latest", "mcp"] } } }
 
 Then ask your agent things like:
   "Explore com.mycompany.app and show me what breaks"

package/docs/BROWSER-PRODUCT.md

@@ -12,7 +12,7 @@ in [`PRODUCT-ENGINE.md`](PRODUCT-ENGINE.md).
 ## Start locally
 
 ```bash
-npx -y @aarwitz/tapp app
+npx -y @aarwitz/tapp@latest app
 ```
 
 Tapp prints an authenticated one-time launch URL and opens it in the default browser. Use

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.0-rc.12",
+  "version": "0.17.0-rc.13",
   "mcpName": "io.github.aarwitz/tapp",
   "description": "Release contracts, autonomous QA, and evidence-backed CI gates for iOS, Android, and web.",
   "license": "MIT",

package/skills/tapp/SKILL.md

@@ -20,15 +20,15 @@ screen or journey works from source inspection alone.
 | Decide whether a merge passes policy | `ci`; exploration never decides this |
 
 Prefer connected `tapp_*` MCP tools when available: they keep interactive sessions alive and return
-screenshots inline. Otherwise run `npx -y @aarwitz/tapp` from the app repository. Do not require MCP,
+screenshots inline. Otherwise run `npx -y @aarwitz/tapp@latest` from the app repository. Do not require MCP,
 an account, an API key, or a global install for the core workflow.
 
 ## Start source-connected
 
 When the user asks for a general first test of a repository:
 
-1. If `.tapp/application-model.json` exists, run `npx -y @aarwitz/tapp explore`.
-2. Otherwise run `npx -y @aarwitz/tapp init . --explore` or call `tapp_init` with
+1. If `.tapp/application-model.json` exists, run `npx -y @aarwitz/tapp@latest explore`.
+2. Otherwise run `npx -y @aarwitz/tapp@latest init . --explore` or call `tapp_init` with
    `{operation:"explore", projectDir:"."}`.
 3. If Tapp returns `target-selection-required`, present its actual choices and ask the user to pick.
    Never guess among multiple targets. Re-run with the selected platform/target exactly as Tapp

package/skills/tapp/references/commands.md

@@ -6,34 +6,34 @@ Run from the application repository. `[target]` is optional when Tapp can read t
 or detect one unambiguous target.
 
 ```bash
-npx -y @aarwitz/tapp init . --explore
-npx -y @aarwitz/tapp explore [target]
-npx -y @aarwitz/tapp open [target]
-npx -y @aarwitz/tapp tree [target] --json
-npx -y @aarwitz/tapp shot
-npx -y @aarwitz/tapp report latest
-npx -y @aarwitz/tapp doctor
+npx -y @aarwitz/tapp@latest init . --explore
+npx -y @aarwitz/tapp@latest explore [target]
+npx -y @aarwitz/tapp@latest open [target]
+npx -y @aarwitz/tapp@latest tree [target] --json
+npx -y @aarwitz/tapp@latest shot
+npx -y @aarwitz/tapp@latest report latest
+npx -y @aarwitz/tapp@latest doctor
 ```
 
 Platform examples:
 
 ```bash
 # Web: Tapp may build/start/stop a source target; --watch is human-visible.
-npx -y @aarwitz/tapp explore --platform web --target website --watch
-npx -y @aarwitz/tapp explore https://staging.example.com
+npx -y @aarwitz/tapp@latest explore --platform web --target website --watch
+npx -y @aarwitz/tapp@latest explore https://staging.example.com
 
 # iOS: source repo, .app, or bundle id.
-npx -y @aarwitz/tapp explore MyApp.xcodeproj --platform ios
-npx -y @aarwitz/tapp open com.example.MyApp --platform ios
+npx -y @aarwitz/tapp@latest explore MyApp.xcodeproj --platform ios
+npx -y @aarwitz/tapp@latest open com.example.MyApp --platform ios
 
 # Android: app id is required; APK is optional if already installed.
-npx -y @aarwitz/tapp explore app-debug.apk --platform android --app-id com.example.app
+npx -y @aarwitz/tapp@latest explore app-debug.apk --platform android --app-id com.example.app
 ```
 
 Focused web evidence can perform one semantic interaction and wait for async content:
 
 ```bash
-npx -y @aarwitz/tapp open https://example.com --tap "Not now" --wait-for "Dashboard"
+npx -y @aarwitz/tapp@latest open https://example.com --tap "Not now" --wait-for "Dashboard"
 ```
 
 ## MCP mapping
@@ -84,8 +84,8 @@ ask the user rather than pretending the explored surface was complete.
 Flow YAML belongs under `.tapp/flows/` and can replay without a model or API key:
 
 ```bash
-npx -y @aarwitz/tapp flow run .tapp/flows/smoke.yml
-npx -y @aarwitz/tapp ci
+npx -y @aarwitz/tapp@latest flow run .tapp/flows/smoke.yml
+npx -y @aarwitz/tapp@latest ci
 ```
 
 `tapp explore` observes. `tapp ci` applies versioned deterministic policy to evidence, selected