@aarwitz/tapp 0.17.0-rc.13 → 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.13",
+  "version": "0.17.0-rc.14",
   "author": {
     "name": "Aaron Horowitz",
     "url": "https://github.com/aarwitz"
@@ -24,7 +24,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@aarwitz/tapp@0.17.0-rc.13",
+        "@aarwitz/tapp@0.17.0-rc.14",
         "mcp"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}"

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)");
       }
@@ -1257,7 +1257,7 @@ switch (command) {
     console.log(`\n  Home: ${tappHome}`);
     console.log(healthy
       ? "\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");
+      : "\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

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.13",
+  "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

@@ -33,8 +33,9 @@ When the user asks for a general first test of a repository:
 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,