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

package/.claude-plugin/marketplace.json

@@ -0,0 +1,34 @@
+{
+  "name": "tapp",
+  "description": "The official Tapp plugin: one agent skill and MCP tools for testing iOS, Android, and web apps on real surfaces.",
+  "owner": {
+    "name": "Aaron Horowitz",
+    "url": "https://github.com/aarwitz"
+  },
+  "plugins": [
+    {
+      "name": "tapp",
+      "source": {
+        "source": "npm",
+        "package": "@aarwitz/tapp"
+      },
+      "description": "Test real iOS, Android, and web apps with Tapp. Includes the Tapp agent skill plus MCP hands, eyes, exploration, replayable Flows, and deterministic release evidence.",
+      "author": {
+        "name": "Aaron Horowitz",
+        "url": "https://github.com/aarwitz"
+      },
+      "homepage": "https://github.com/aarwitz/tapp",
+      "license": "MIT",
+      "keywords": [
+        "ios",
+        "simulator",
+        "testing",
+        "qa",
+        "xcuitest",
+        "mcp",
+        "agent-skill",
+        "copilot"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

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

package/AGENTS.md

@@ -12,6 +12,7 @@ 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)
@@ -22,8 +23,10 @@ npx -y @aarwitz/tapp flow run .tapp/flows/smoke.yml  # committed, keyless E2E re
 ```
 
 If repository onboarding detects multiple application targets, target detection is deterministic but
-the choice is the user's. 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
+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
@@ -41,7 +44,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

package/README.md

@@ -4,8 +4,10 @@
 [![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)
+[![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=)
-[![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)
+[![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)
 
 **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
@@ -31,6 +33,47 @@ Three platforms, one observe-and-gate engine:
   autonomous exploration, the deterministic detectors (uncaught exceptions, failed requests,
   dead buttons, broken links, placeholder `href="#"` links, error pages), and the same gate.
 
+## 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
+release judgment.
+
+**Claude Code — skill and MCP tools together:**
+
+```bash
+claude plugin marketplace add aarwitz/tapp
+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.
+
+**Claude, Codex, Cursor, Copilot, and other Agent Skills clients — skill only:**
+
+```bash
+npx -y skills add aarwitz/tapp --skill tapp
+```
+
+This installs the open Agent Skills version of the same instructions into the current project and
+lets the agent fall back to the npm CLI when MCP is not connected. Add `-g` for a user-wide install,
+or `--agent claude-code`, `--agent codex`, and similar selectors to constrain the clients.
+
+**No agent integration:** run the npm package directly from an app repository:
+
+```bash
+npx -y @aarwitz/tapp init . --explore
+```
+
+**VS Code:** install [Tapp from the Marketplace](https://marketplace.visualstudio.com/items?itemName=lidi-solutions.tapp).
+It contributes the same cross-platform Agent Skill to Copilot plus focused iOS simulator tools and a
+live simulator panel. Android and web remain available through the skill's CLI/MCP workflow.
+
 ```
 you:    "Add a logout button to the settings screen"
 agent:  *writes the Swift*
@@ -38,7 +81,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.
@@ -80,11 +123,14 @@ npx -y @aarwitz/tapp baseline create . --platform web
 npx -y @aarwitz/tapp ci install .
 ```
 
-On a fresh repository containing multiple apps (for example, iOS plus web), bare
-`tapp init . --explore` does not guess from detection order. A human terminal gets a numbered
+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`.
+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
@@ -106,7 +152,9 @@ npx -y @aarwitz/tapp build [dir]     # just build + install (scheme auto-detecte
 ```
 
 Web (beta): `npx -y @aarwitz/tapp explore http://localhost:3000` *(one-time setup:
-`npm i -g playwright && npx playwright install chromium`)*
+`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:
@@ -191,7 +239,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

package/bin/tapp.js

@@ -240,8 +240,8 @@ async function resolveTargetOrExit(engine, input) {
 
 function safeCommandUsage(verb) {
   const usage = {
-    explore: "tapp explore [target] [--platform ios|android|web] [--actions N] [--timeout SEC] [--email VALUE] [--password VALUE] [--baseline FILE] [--json FILE]\n  iOS launch configuration: [--launch-arg VALUE ...] [--launch-env '{\"KEY\":\"VALUE\"}']\n  Android: [--app-id ID] [--apk FILE] [--serial ID] [--keep-data]",
-    init: "tapp init [repo] [--explore] [--refresh] [--platform PLATFORM] [--target NAME] [--url URL] [--dry-run]",
+    explore: "tapp explore [target] [--platform ios|android|web] [--actions N] [--timeout SEC] [--email VALUE] [--password VALUE] [--baseline FILE] [--json FILE]\n  Web: [--watch] opens Tapp's controlled browser and shows its actions\n  iOS launch configuration: [--launch-arg VALUE ...] [--launch-env '{\"KEY\":\"VALUE\"}']\n  Android: [--app-id ID] [--apk FILE] [--serial ID] [--keep-data]",
+    init: "tapp init [repo] [--explore] [--refresh] [--platform PLATFORM] [--target NAME] [--url URL] [--watch] [--dry-run]",
     open: "tapp open [target] [--platform ios|android|web] [--out FILE] [--tap TEXT] [--wait-for TEXT]",
     tree: "tapp tree [target] [--platform ios|android|web] [--json] [--tap TEXT] [--wait-for TEXT]",
     shot: "tapp shot [--out FILE]",
@@ -346,6 +346,7 @@ switch (command) {
       timeout,
       testEmail: typeof flags.email === "string" ? flags.email : undefined,
       testPassword: typeof flags.password === "string" ? flags.password : undefined,
+      watch: flags.watch === true,
       runExploration: engine?.runInitExploration,
       onProgress: (progress) => {
         const activePlatform = progress.platform || platform;
@@ -387,17 +388,29 @@ switch (command) {
     if (typeof flags["json-out"] === "string") {
       const out = path.resolve(flags["json-out"]);
       fs.mkdirSync(path.dirname(out), { recursive: true });
-      fs.writeFileSync(out, JSON.stringify({ model: built.model, plan: written?.plan || built.plan, ...(exploration ? { exploration } : {}) }, null, 2) + "\n");
-    }
-    const blocking = built.model.requirements.filter((item) => item.severity === "blocking");
+      fs.writeFileSync(out, JSON.stringify({
+        model: built.model,
+        plan: written?.plan || built.plan,
+        ...(exploration ? { exploration } : {}),
+        ...(result.selectedTarget ? { selectedTarget: result.selectedTarget } : {}),
+        requirementScope: result.requirementScope,
+      }, null, 2) + "\n");
+    }
+    const activeRequirements = result.requirementScope?.active || built.model.requirements;
+    const deferredRequirements = result.requirementScope?.deferred || [];
+    const blocking = activeRequirements.filter((item) => item.severity === "blocking");
+    const deferredBlocking = deferredRequirements.filter((item) => item.severity === "blocking");
     const pending = (written?.plan || built.plan).items.filter((item) => item.decision === "pending");
     console.log(`🧭 Tapp init — ${built.model.application.name}`);
     console.log(`   targets: ${built.model.targets.length ? built.model.targets.map((target) => `${target.platform}:${target.name}`).join(", ") : "none"}`);
     console.log(`   UI Map: ${built.model.uiMap.status} · ${built.model.uiMap.nodeCount} states · ${built.model.uiMap.edgeCount} transitions`);
     if (exploration) console.log(`   Exploration: ${(exploration.findings || []).length} finding(s)${exploration.inconclusive ? " (inconclusive)" : ""} · ${exploration.uiMap.nodeCount} states · evidence: ${exploration.reportHtml || exploration.capture?.path || "capture recorded"}`);
     if (exploration?.managedRuntime) console.log(`   Managed web runtime: built/started ${exploration.target} for exploration and stopped it afterward · log: ${exploration.runtime.logPath}`);
-    console.log(`   release plan: ${(written?.plan || built.plan).items.length} item(s) · ${pending.length} pending review · ${blocking.length} blocking requirement(s)`);
-    for (const requirement of built.model.requirements) console.log(`   ${requirement.severity === "blocking" ? "❌" : "⚠️"} ${requirement.message} Next: ${requirement.remediation}`);
+    const selectedLabel = result.selectedTarget ? ` for ${result.selectedTarget.platform}:${result.selectedTarget.name}` : "";
+    const deferredLabel = deferredBlocking.length ? ` · ${deferredBlocking.length} setup gap(s) on unselected target(s)` : "";
+    console.log(`   release plan: ${(written?.plan || built.plan).items.length} item(s) · ${pending.length} pending review · ${blocking.length} blocking requirement(s)${selectedLabel}${deferredLabel}`);
+    for (const requirement of activeRequirements) console.log(`   ${requirement.severity === "blocking" ? "❌" : "⚠️"} ${requirement.message} Next: ${requirement.remediation}`);
+    for (const requirement of deferredRequirements) console.log(`   ℹ️ Unselected ${requirement.targetPlatform}:${requirement.targetName} setup gap: ${requirement.message} Next: ${requirement.remediation}`);
     if (written) console.log(`   model: ${written.modelPath}\n   plan: ${written.planPath}`);
     else console.log("   dry run: repository files were not changed");
     break;
@@ -545,6 +558,7 @@ switch (command) {
           testPassword: flags.password,
           ...launchOptions,
           baselineFindings,
+          watch: flags.watch === true,
           surface: "cli",
           onProgress,
           onStatus: (t) => console.error(`ℹ️  ${t}`),
@@ -565,6 +579,10 @@ switch (command) {
       process.exit(2);
     }
     if (platform === "ios") requireMacFor("iOS testing");
+    if (flags.watch === true && platform !== "web") {
+      console.error("❌ --watch is currently available for web exploration only");
+      process.exit(2);
+    }
     if (platform !== "ios" && Object.keys(launchOptions).length) {
       console.error("❌ --launch-arg and --launch-env apply only to iOS targets");
       process.exit(2);
@@ -586,6 +604,7 @@ switch (command) {
           testEmail: flags.email,
           testPassword: flags.password,
           baselineFindings,
+          watch: flags.watch === true,
           surface: "cli",
           onProgress,
         })
@@ -1557,7 +1576,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)
-                           (--platform ios|android|web · --app-id ID · --apk FILE · --actions N)
+                           (web: --watch · all: --platform ios|android|web · --actions N)
   tapp contract run FILE   Replay a business-level release contract — the guarantees that must hold
   tapp ci ...              Merge-blocking release gate — explore + suites + baseline → pass/fail/inconclusive
                            (see: tapp ci --help)
@@ -1617,6 +1636,11 @@ Setup:
   tapp doctor     Check Xcode / simulators / toolchain
   tapp mcp        Start the MCP server on stdio (adds inline screenshots + interactive sessions)
 
+Agent Skill (optional — so a short “Use Tapp to test this app” prompt is enough):
+  Any supported agent: npx -y skills add aarwitz/tapp --skill tapp
+  Claude skill + MCP:  claude plugin marketplace add aarwitz/tapp
+                       claude plugin install tapp@tapp
+
 MCP hookup (optional — for inline screenshots and the tap/type/inspect session loop):
   Claude Code:   claude mcp add tapp -- npx -y @aarwitz/tapp mcp
   Cursor/VS Code (mcp.json):

package/docs/application-model.md

@@ -16,12 +16,14 @@ resolution actually builds and installs the detected Xcode container, the model
 scheme as runtime-observed validation and removes the corresponding confirmation blocker. Merely
 supplying a bundle id or prebuilt `.app` does not prove repository build configuration.
 
-A fresh repository with more than one detected application target is never resolved by detection
-order. Bare `tapp init . --explore` prompts in a human TTY; non-interactive CLI/MCP callers receive
+A repository with more than one detected application target is never resolved by detection order
+during explicit initialization, even when a prior default exists. Bare `tapp init . --explore`
+prompts in a human TTY; non-interactive CLI/MCP callers receive
 exact `--platform`/`--target` commands before any build or write, and MCP also carries them as
 structured `target-selection-required` choices. The selected run records that target as the default
-for later bare exploration, but the application model retains the repository's other detected targets
-and their unmet coverage.
+for later bare `tapp explore`, but the application model retains the repository's other detected
+targets and their unmet coverage. The selected init run reports other-target setup gaps as deferred
+information rather than presenting them as failures of the target that was actually explored.
 
 ## First inspection