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

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.14",
   "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.14",
         "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

@@ -155,7 +155,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);
 }
 
@@ -840,7 +840,7 @@ switch (command) {
       process.exit(1);
     }
     console.log(`🔨 Built ${path.basename(built.appPath)} (scheme ${built.scheme}) — installed as ${inst.bundleId}`);
-    console.log(`\nNext: tapp explore ${inst.bundleId}`);
+    console.log(`\nNext: npx -y @aarwitz/tapp@latest explore ${inst.bundleId}`);
     break;
   }
 
@@ -1054,7 +1054,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;
     }
@@ -1223,7 +1223,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)");
       }
@@ -1256,8 +1256,8 @@ 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]"
-      : "\nFix the ❌ items above, then re-run: tapp doctor");
+      ? "\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: npx -y @aarwitz/tapp@latest doctor");
     process.exit(healthy ? 0 : 1);
   }
 
@@ -1332,7 +1332,7 @@ 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.");
+      console.log("   No credential values were accepted or written. Rerun npx -y @aarwitz/tapp@latest init --refresh to update the application model.");
     } catch (error) { console.error(`❌ Actor not configured: ${error.message || String(error)}`); process.exit(2); }
     break;
   }
@@ -1347,7 +1347,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 +1454,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}`;
@@ -1575,7 +1575,7 @@ switch (command) {
 
 Core — explore, prove, gate (agents and humans can just run these — no server, no setup):
   tapp explore [target]    Autonomous exploration → findings + evidence (an observation, NOT a
-                           release decision — run 'tapp ci' to gate a merge)
+                           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
@@ -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/mcp-server/src/application-model.js

@@ -541,10 +541,10 @@ export async function inspectApplicationRepository({ projectDir, ownedUrl = "",
   const requirements = [];
   if (!targets.length) requirements.push({ id: "target", severity: "blocking", status: "missing", message: "No iOS application project, Android application module, or browser application target was detected.", remediation: "Pass the representative target explicitly or add its unavoidable build/runtime configuration." });
   for (const target of targets) {
-    if (target.platform === "ios" && target.status !== "configured") requirements.push({ id: `${target.id}:scheme`, severity: "blocking", status: "needs-confirmation", message: `Confirm a shared build scheme for ${target.name}.`, remediation: `Run tapp build ${target.sourcePath} or provide the scheme during init/build.` });
+    if (target.platform === "ios" && target.status !== "configured") requirements.push({ id: `${target.id}:scheme`, severity: "blocking", status: "needs-confirmation", message: `Confirm a shared build scheme for ${target.name}.`, remediation: `Run npx -y @aarwitz/tapp@latest build ${target.sourcePath} or provide the scheme during init/build.` });
     if (target.platform === "android" && !target.runtime.applicationId) requirements.push({ id: `${target.id}:application-id`, severity: "blocking", status: "missing", message: `Android application id was not statically detected for ${target.name}.`, remediation: "Provide --app-id or expose applicationId in the application module." });
-    if (target.platform === "web" && !target.runtime.ownedUrl && target.runtime.management !== "tapp-managed") requirements.push({ id: `${target.id}:owned-url`, severity: "blocking", status: "missing", message: `No safe managed runtime or owned URL is available for ${target.name}.`, remediation: "Add a deterministic start/static target or start the app and rerun tapp init with --url http://127.0.0.1:<port>." });
-    if (target.platform === "web" && target.build.dependencyStatus === "missing-lockfile") requirements.push({ id: `${target.id}:dependency-lock`, severity: "blocking", status: "missing", message: `${target.name} declares browser dependencies without an observed dependency lockfile.`, remediation: "Commit the package-manager lockfile so Tapp can install dependencies reproducibly, then rerun tapp init." });
+    if (target.platform === "web" && !target.runtime.ownedUrl && target.runtime.management !== "tapp-managed") requirements.push({ id: `${target.id}:owned-url`, severity: "blocking", status: "missing", message: `No safe managed runtime or owned URL is available for ${target.name}.`, remediation: "Add a deterministic start/static target or start the app and rerun npx -y @aarwitz/tapp@latest init with --url http://127.0.0.1:<port>." });
+    if (target.platform === "web" && target.build.dependencyStatus === "missing-lockfile") requirements.push({ id: `${target.id}:dependency-lock`, severity: "blocking", status: "missing", message: `${target.name} declares browser dependencies without an observed dependency lockfile.`, remediation: "Commit the package-manager lockfile so Tapp can install dependencies reproducibly, then rerun npx -y @aarwitz/tapp@latest init." });
   }
   const incompleteMaps = uiMaps.filter((record) => record.summary.status !== "observed");
   for (const record of incompleteMaps.length ? incompleteMaps : (!targets.length && uiMap.status !== "observed" ? [{ summary: uiMap }] : [])) {
@@ -553,7 +553,7 @@ export async function inspectApplicationRepository({ projectDir, ownedUrl = "",
     requirements.push({
       id: targets.length <= 1 ? "ui-map" : `${target.id}:ui-map`, severity: "blocking", status: summary.status === "inconclusive" ? "inconclusive" : "missing",
       message: target ? (summary.status === "inconclusive" ? `The UI Map for ${target.name} is inconclusive.` : `No grounded UI Map exists for ${target.name}.`) : "No repository UI Map has been grounded in a real run.",
-      remediation: target ? `Build/launch ${target.name}, explore the real target, and retain its map at ${summary.expectedPath || summary.path}.` : "Build/launch the target and run tapp init --explore so real exploration evidence is merged into .tapp/ui-map.json.",
+      remediation: target ? `Build/launch ${target.name}, explore the real target, and retain its map at ${summary.expectedPath || summary.path}.` : "Build/launch the target and run npx -y @aarwitz/tapp@latest init --explore so real exploration evidence is merged into .tapp/ui-map.json.",
     });
   }
   if (!contracts.length) requirements.push({ id: "contracts", severity: "warning", status: "missing", message: "No reviewed release contracts exist yet.", remediation: "Review the proposed release plan, then generate and validate a compact set of contracts." });
@@ -561,7 +561,7 @@ export async function inspectApplicationRepository({ projectDir, ownedUrl = "",
   for (const error of projectConfiguration.errors) requirements.push({ id: stableId("project-config-error", error), severity: "blocking", status: "invalid", message: error, remediation: `Fix ${projectConfiguration.relativePath}; actor configuration must contain environment-variable bindings, never credential values.` });
   for (const actor of actors) {
     const missingBindings = actor.credentialRequirements.filter((credential) => !actor.credentialBindings[credential]);
-    if (missingBindings.length) requirements.push({ id: `actor:${actor.name}:credential-bindings`, severity: "blocking", status: "missing", message: `Actor '${actor.name}' has unbound credential requirements: ${missingBindings.join(", ")}.`, remediation: `Run tapp actor set ${actor.name} --credential <name>=<ENV_NAME> for each credential, then replace any literal contract credentials with $ENV_NAME placeholders.` });
+    if (missingBindings.length) requirements.push({ id: `actor:${actor.name}:credential-bindings`, severity: "blocking", status: "missing", message: `Actor '${actor.name}' has unbound credential requirements: ${missingBindings.join(", ")}.`, remediation: `Run npx -y @aarwitz/tapp@latest actor set ${actor.name} --credential <name>=<ENV_NAME> for each credential, then replace any literal contract credentials with $ENV_NAME placeholders.` });
     if (actor.bindingConflicts.length) requirements.push({ id: `actor:${actor.name}:credential-conflicts`, severity: "blocking", status: "conflict", message: `Actor '${actor.name}' has conflicting credential environment bindings.`, remediation: `Align ${projectConfiguration.relativePath} and reviewed contracts; Tapp will not guess which secret binding is correct.` });
   }
   for (const error of taskErrors) requirements.push({ id: stableId("task-error", error.path), severity: "blocking", status: "invalid", message: error.error, remediation: `Fix ${error.path} before generation.` });
@@ -997,7 +997,7 @@ function edgeSupportsPlatform(edge, nodes, platform) {
 function shortestObservedPath(map, platform, targetId, { startNodeId } = {}) {
   const nodes = new Map((map.nodes || []).map((node) => [node.id, node]));
   const entryId = startNodeId || map.app?.navigationRoots?.[platform] || map.app?.entryNodes?.[platform];
-  if (!entryId || !nodes.has(entryId)) throw new Error(`UI Map has no observed ${platform} navigation root; rerun tapp init --refresh --explore before generating Tasks`);
+  if (!entryId || !nodes.has(entryId)) throw new Error(`UI Map has no observed ${platform} navigation root; rerun npx -y @aarwitz/tapp@latest init --refresh --explore before generating Tasks`);
   if (!nodes.has(targetId)) throw new Error(`UI Map proposal target '${targetId}' is no longer present`);
   if (entryId === targetId) return [];
   const outgoing = new Map();

package/mcp-server/src/ci-report.js

@@ -422,10 +422,10 @@ function renderMarkdown(report, regression, flows, scenarios, contracts, prPlan,
         ? ` at \`${target.navigation.route}\``
         : target.navigation?.mode === "ui-map-path" ? ` through ${(target.navigation.steps || []).length} observed map edge(s)` : "";
       lines.push(`- ${icon} PR exploration **${target.node?.name || target.id}** — ${target.execution?.status || target.status}${navigation}`);
-      if (target.coverageProposal?.status === "awaiting-explicit-adoption") lines.push(`  - Reviewable coverage proposal ready; never auto-applied. Next: \`tapp pr adopt <pr-plan.json> --item ${target.id} --project-dir .\``);
+      if (target.coverageProposal?.status === "awaiting-explicit-adoption") lines.push(`  - Reviewable coverage proposal ready; never auto-applied. Next: \`npx -y @aarwitz/tapp@latest pr adopt <pr-plan.json> --item ${target.id} --project-dir .\``);
       if (target.existingReleasePlanItem) {
         lines.push(`  - Existing release-plan item \`${target.existingReleasePlanItem.name}\` remains ${target.existingReleasePlanItem.decision}; no duplicate or decision change was made.`);
-        lines.push(`  - Optional explicit evidence reconciliation: \`tapp pr adopt <pr-plan.json> --item ${target.id} --project-dir .\``);
+        lines.push(`  - Optional explicit evidence reconciliation: \`npx -y @aarwitz/tapp@latest pr adopt <pr-plan.json> --item ${target.id} --project-dir .\``);
       }
     }
     for (const candidate of prPlan.maintenanceCandidates || []) {

package/mcp-server/src/ci-setup.js

@@ -17,7 +17,7 @@ export function targetSlug(value) {
 
 export function selectApplicationTarget(model, { platform = "", target = "", useDefault = false } = {}) {
   if (model?.kind !== "tapp-application-model" || !Array.isArray(model.targets)) {
-    throw new Error("Expected a Tapp application model; run tapp init first");
+    throw new Error("Expected a Tapp application model; run npx -y @aarwitz/tapp@latest init first");
   }
   const selectedPlatform = String(platform || "").toLowerCase();
   let candidates = model.targets.filter((item) => !selectedPlatform || item.platform === selectedPlatform);
@@ -215,7 +215,7 @@ function credentialConfiguration(model, targetContracts = []) {
     if (requirements.has("email")) bindings.add("TAPP_TEST_EMAIL");
     if (requirements.has("password")) bindings.add("TAPP_TEST_PASSWORD");
   }
-  for (const name of bindings) if (!/^[A-Z_][A-Z0-9_]{0,127}$/.test(String(name))) throw new Error(`Actor credential binding '${name}' is not a safe environment-variable name; rerun tapp init from valid .tapp/project.json`);
+  for (const name of bindings) if (!/^[A-Z_][A-Z0-9_]{0,127}$/.test(String(name))) throw new Error(`Actor credential binding '${name}' is not a safe environment-variable name; rerun npx -y @aarwitz/tapp@latest init from valid .tapp/project.json`);
   const inputs = {};
   const primaryEmail = primary.credentialBindings?.email || (!primary.credentialBindings && requirements.has("email") ? "TAPP_TEST_EMAIL" : "");
   const primaryPassword = primary.credentialBindings?.password || (!primary.credentialBindings && requirements.has("password") ? "TAPP_TEST_PASSWORD" : "");
@@ -241,7 +241,7 @@ function targetInputs(root, model, target) {
     const androidProjectPath = path.resolve(root, androidProject);
     const androidProjectRelative = path.relative(root, androidProjectPath);
     if (path.isAbsolute(androidProjectRelative) || androidProjectRelative === ".." || androidProjectRelative.startsWith(`..${path.sep}`)) unresolved.push("Android Gradle project resolves outside the repository");
-    else if (!fs.existsSync(path.join(androidProjectPath, "gradlew"))) unresolved.push(`Gradle wrapper is missing from ${androidProject}; commit gradlew or rerun tapp init from the Gradle repository root`);
+    else if (!fs.existsSync(path.join(androidProjectPath, "gradlew"))) unresolved.push(`Gradle wrapper is missing from ${androidProject}; commit gradlew or rerun npx -y @aarwitz/tapp@latest init from the Gradle repository root`);
     inputs["android-project"] = androidProject;
     inputs["android-task"] = target.build?.task || "assembleDebug";
     if (target.runtime?.applicationId) inputs["android-app-id"] = target.runtime.applicationId;
@@ -282,7 +282,7 @@ export function renderGithubWorkflow({ projectDir, model, actionRef, defaultBran
   const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
   if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+@[A-Za-z0-9_.-]+$/.test(String(actionRef || ""))) throw new Error("--action-ref must be owner/repository@release-tag-or-sha");
   if (!/^[A-Za-z0-9._\/-]+$/.test(defaultBranch) || defaultBranch.startsWith("/")) throw new Error("--default-branch contains unsupported characters");
-  if (model?.kind !== "tapp-application-model" || !Array.isArray(model.targets) || !model.targets.length) throw new Error("Application model has no targets; run tapp init first");
+  if (model?.kind !== "tapp-application-model" || !Array.isArray(model.targets) || !model.targets.length) throw new Error("Application model has no targets; run npx -y @aarwitz/tapp@latest init first");
   const occupied = new Set();
   const jobs = [];
   const manifestTargets = [];

package/mcp-server/src/index.js

@@ -1335,9 +1335,9 @@ function fmtDuration(ms) {
 export function qaNextSteps(report, surface = "mcp") {
   if (surface === "cli") {
     const next = [];
-    if (report?.findings?.length) next.push("inspect the evidence with `tapp report latest`");
-    next.push("re-run with `--baseline <report.json>` to compare a fix (then `tapp ci` to gate it)");
-    next.push("replay a committed journey with `tapp flow run <file>`");
+    if (report?.findings?.length) next.push("inspect the evidence with `npx -y @aarwitz/tapp@latest report latest`");
+    next.push("re-run with `--baseline <report.json>` to compare a fix (then `npx -y @aarwitz/tapp@latest ci` to gate it)");
+    next.push("replay a committed journey with `npx -y @aarwitz/tapp@latest flow run <file>`");
     return next;
   }
   const next = [];
@@ -1390,7 +1390,7 @@ function formatQaReport(report, { regression, inputHint, timedOut, bundleId, aiC
     // The merge decision is the gate's job (tapp ci), not exploration's (ADR-0005).
     L.push("");
     L.push(
-      `**Since last run** — +${regression.counts.new} new · ${regression.counts.persisting} persisting · ${regression.counts.resolved} resolved (comparison only — run \`tapp ci\` to gate)`
+      `**Since last run** — +${regression.counts.new} new · ${regression.counts.persisting} persisting · ${regression.counts.resolved} resolved (comparison only — run \`npx -y @aarwitz/tapp@latest ci\` to gate)`
     );
   }
   if (inputHint) {
@@ -1801,7 +1801,7 @@ export async function runExploreTarget({
 
   const modelPath = existingProjectArtifactPath(root, "application-model.json");
   if (!fs.existsSync(modelPath)) {
-    return { error: "No application model found — run `tapp init` first, or pass an explicit target (a bundle id, a path/to/App.app, a repo dir, --app-id/--apk, or an http(s) URL)." };
+    return { error: "No application model found — call `tapp_init` or run `npx -y @aarwitz/tapp@latest init` first, or pass an explicit target (a bundle id, a path/to/App.app, a repo dir, --app-id/--apk, or an http(s) URL)." };
   }
   let model;
   try { model = JSON.parse(fs.readFileSync(modelPath, "utf8")); }
@@ -1839,7 +1839,7 @@ export async function runExploreTarget({
 
   if (selectedPlatform === "android") {
     const appId = String(selected.runtime?.applicationId || "").trim();
-    if (!appId) return { error: `The Android target '${selected.name}' has no confirmed application id — confirm it and rerun \`tapp init\`, or pass --app-id.` };
+    if (!appId) return { error: `The Android target '${selected.name}' has no confirmed application id — confirm it and call \`tapp_init\` or rerun \`npx -y @aarwitz/tapp@latest init\`, or pass --app-id.` };
     const task = selected.build?.task || "assembleDebug";
     onStatus(`Building the Android APK (${task})…`);
     const built = await buildAndroidApp({
@@ -2322,7 +2322,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
               "Findings from a previous run (pass back the `findings` array a prior tapp_explore returned). " +
               "When provided, the result adds a `regression` COMPARISON {counts:{new,persisting,resolved}, " +
               "newFindings, resolved} vs. that baseline — an observation, not a gate signal. To gate a merge, " +
-              "run `tapp ci` (or the GitHub Action): it applies the deterministic policy and returns the " +
+              "run `npx -y @aarwitz/tapp@latest ci` (or the GitHub Action): it applies the deterministic policy and returns the " +
               "pass/fail/inconclusive outcome.",
           },
         },
@@ -2858,7 +2858,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const icon = c.ok ? "✅" : c.required ? "❌" : "⚪️";
       L.push(`- ${icon} **${c.check}** — ${String(c.value).split("\n")[0] || "—"}`);
     }
-    if (!ready) L.push("", "Run `tapp doctor` in the application repository for exact remediation.");
+    if (!ready) L.push("", "Run `npx -y @aarwitz/tapp@latest doctor` in the application repository for exact remediation.");
     return richResult(L.join("\n"), { ok: ready, workspaceRoot, checks, platforms: Object.fromEntries(platformChecks.map((check) => [check.check.toLowerCase(), check.ok])) });
   }
 

package/mcp-server/src/pr-selection.js

@@ -410,7 +410,7 @@ export function adoptPrCoverageProposal({ projectDir, prPlanPath, item, releaseP
   if (!prPlanPath || !fs.existsSync(source)) throw new Error(`PR plan not found: ${source || "(missing path)"}`);
   const targetPath = releasePlanPath === ".tapp/release-plan.json" ? existingProjectArtifactPath(root, "release-plan.json") : path.resolve(root, releasePlanPath);
   if (!inside(root, targetPath)) throw new Error("Release plan path must stay inside the project directory");
-  if (!fs.existsSync(targetPath)) throw new Error(`Release plan not found: ${targetPath}; run tapp init first`);
+  if (!fs.existsSync(targetPath)) throw new Error(`Release plan not found: ${targetPath}; run npx -y @aarwitz/tapp@latest init first`);
   const prPlan = JSON.parse(fs.readFileSync(source, "utf8"));
   if (prPlan?.schemaVersion !== 1 || !Array.isArray(prPlan.explorationTargets)) throw new Error("PR plan must be an executed Tapp PR plan v1");
   const matches = prPlan.explorationTargets.filter((target) => target.id === item);
@@ -428,7 +428,7 @@ export function adoptPrCoverageProposal({ projectDir, prPlanPath, item, releaseP
   if (!ground || !fs.existsSync(mapPath)) throw new Error("Coverage proposal requires the repository's persistent UI Map");
   const map = JSON.parse(fs.readFileSync(mapPath, "utf8"));
   const node = (map.nodes || []).find((candidate) => candidate.id === ground.id && candidate.status !== "proposed");
-  const refreshAdvice = "refresh the persistent UI Map with `tapp init --explore --refresh`, rerun `tapp pr gate`, then retry `tapp pr adopt`";
+  const refreshAdvice = "refresh the persistent UI Map with `npx -y @aarwitz/tapp@latest init --explore --refresh`, rerun `npx -y @aarwitz/tapp@latest pr gate`, then retry `npx -y @aarwitz/tapp@latest pr adopt`";
   if (!node) throw new Error(`Coverage proposal UI Map node is stale or missing: ${ground.id}; ${refreshAdvice}`);
   if (target.navigation?.route && !(node.routes || []).some((route) => route.platform === target.platform && route.path === target.navigation.route && route.replayable === true)) {
     throw new Error(`Coverage proposal route is stale in the persistent UI Map: ${target.navigation.route}; ${refreshAdvice}`);

package/mcp-server/src/product-operations.js

@@ -79,7 +79,7 @@ function initTargetChoices(model, platform = "") {
   const candidates = (model.targets || []).filter((target) => !platform || target.platform === platform);
   return candidates.map((target) => ({
     target,
-    command: `tapp init . --explore --platform ${target.platform} --target ${target.sourcePath === "." ? JSON.stringify(target.name) : JSON.stringify(target.sourcePath)}`,
+    command: `npx -y @aarwitz/tapp@latest init . --explore --platform ${target.platform} --target ${target.sourcePath === "." ? JSON.stringify(target.name) : JSON.stringify(target.sourcePath)}`,
   }));
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.0-rc.12",
+  "version": "0.17.0-rc.14",
   "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,21 +20,22 @@ 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
    instructs.
-4. If a prerequisite is missing, run `tapp doctor`, apply only the stated remediation that is in
-   scope, and retry once.
+4. If a prerequisite is missing, call `tapp_health` when MCP is connected or run
+   `npx -y @aarwitz/tapp@latest doctor`, apply only the stated remediation that is in scope, and
+   retry once.
 
 For a focused request, use the requested target directly rather than forcing repository onboarding.
 Targets may be a repository path, Xcode container, `.app`, iOS bundle id, APK plus Android app id,

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