@aarwitz/tapp 0.15.0 → 0.16.0

package/mcp-server/src/index.js

@@ -13,15 +13,16 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 import { parseOcqaMarkers, buildQaReport, computeRegression } from "./report.js";
+import { existingProjectArtifactPath, projectArtifactDirectory } from "./project-paths.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const repoRoot = path.resolve(__dirname, "../..");
 const scriptsDir = path.join(repoRoot, "scripts");
-// AUTOTAP_HOME (set by the `tapp` CLI when running as an installed npm package) redirects
-// all writable output to a user dir; unset (repo dev flow) captures stay in the repo.
-const autotapHome = (process.env.AUTOTAP_HOME || "").trim();
-const capturesDir = autotapHome ? path.join(autotapHome, "captures") : path.join(repoRoot, "captures");
+// TAPP_HOME (set by the `tapp` CLI when installed) redirects writable output to a user directory.
+// The old alias remains a read-only fallback; unset repository development stays local.
+const tappHome = (process.env.TAPP_HOME || process.env.AUTOTAP_HOME || "").trim();
+const capturesDir = tappHome ? path.join(tappHome, "captures") : path.join(repoRoot, "captures");
 const MAX_OUTPUT_CHARS = 60_000;
 const requiredAuthToken = (process.env.TAPP_MCP_TOKEN || process.env.AUTOTAP_MCP_TOKEN || "").trim();
 
@@ -83,7 +84,7 @@ function ensureAuthorized(args = {}) {
   const provided = typeof args.authToken === "string" ? args.authToken.trim() : "";
   if (provided !== requiredAuthToken) {
     return errorResult("Unauthorized", {
-      reason: "Provide valid authToken when AUTOTAP_MCP_TOKEN is set",
+      reason: "Provide valid authToken when TAPP_MCP_TOKEN is set",
     });
   }
 
@@ -339,7 +340,7 @@ export async function buildAppForSim({ dir, container, scheme, configuration = "
       };
     }
   }
-  const derived = path.join(autotapHome || os.tmpdir(), "app-builds", schemeName.replace(/[^a-zA-Z0-9]/g, "_"));
+  const derived = path.join(tappHome || os.tmpdir(), "app-builds", schemeName.replace(/[^a-zA-Z0-9]/g, "_"));
   const build = await runCommand(
     "xcodebuild",
     [
@@ -918,7 +919,7 @@ export async function saveInteractiveSessionFlow({ projectDir, name, addFinalAss
     steps,
   };
   const slug = flowName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "flow";
-  const dir = path.join(root, ".autotap", "flows");
+  const dir = path.join(root, ".tapp", "flows");
   const outPath = path.join(dir, `${slug}.yml`);
   if (fs.existsSync(outPath) && !replace) {
     const error = new Error(`Flow '${path.relative(root, outPath)}' already exists. Choose another name or explicitly replace it.`);
@@ -1065,7 +1066,7 @@ export async function captureScreenshotImage(maxWidth) {
 // change data-handling behavior. A subscription token is an explicit tapp choice, and
 // explicitly-invoked AI tools (tapp_flow_generate, assert_ai) carry their own consent.
 export function remoteAiOptedIn(env = process.env) {
-  if ((env.AUTOTAP_SUBSCRIPTION_TOKEN || env.TAPP_SUBSCRIPTION_TOKEN || "").trim()) return true;
+  if ((env.TAPP_SUBSCRIPTION_TOKEN || env.AUTOTAP_SUBSCRIPTION_TOKEN || "").trim()) return true;
   return ["1", "true", "yes"].includes(String(env.TAPP_ENABLE_REMOTE_AI || "").trim().toLowerCase());
 }
 
@@ -1077,9 +1078,9 @@ export function isInsideDir(root, p) {
 }
 
 function resolveModelBackend() {
-  const token = (process.env.AUTOTAP_SUBSCRIPTION_TOKEN || "").trim();
+  const token = (process.env.TAPP_SUBSCRIPTION_TOKEN || process.env.AUTOTAP_SUBSCRIPTION_TOKEN || "").trim();
   if (token) {
-    const base = (process.env.AUTOTAP_PROXY_URL || "http://localhost:8787").replace(/\/$/, "");
+    const base = (process.env.TAPP_PROXY_URL || process.env.AUTOTAP_PROXY_URL || "http://localhost:8787").replace(/\/$/, "");
     const url = base.endsWith("/v1/messages") ? base : base + "/v1/messages";
     return { url, headers: { authorization: `Bearer ${token}`, "content-type": "application/json" } };
   }
@@ -1091,7 +1092,7 @@ function resolveModelBackend() {
 }
 
 async function callModel(backend, { system, userText, model, maxTokens = 1500 }) {
-  const body = JSON.stringify({ model: model || process.env.AUTOTAP_FLOW_MODEL || "claude-sonnet-4-6", max_tokens: maxTokens, system, messages: [{ role: "user", content: userText }] });
+  const body = JSON.stringify({ model: model || process.env.TAPP_FLOW_MODEL || process.env.AUTOTAP_FLOW_MODEL || "claude-sonnet-4-6", max_tokens: maxTokens, system, messages: [{ role: "user", content: userText }] });
   const res = await fetch(backend.url, { method: "POST", headers: backend.headers, body });
   if (!res.ok) return { error: `model HTTP ${res.status}: ${(await res.text()).slice(0, 300)}` };
   const data = await res.json();
@@ -1589,7 +1590,7 @@ export async function runQaIos({ bundleId, maxActions, timeout, args = {}, onPro
 export async function runInitExploration({
   projectDir,
   platform,
-  outDir = ".autotap",
+  outDir = ".tapp",
   url = "",
   target = "",
   bundleId = "",
@@ -1610,7 +1611,7 @@ export async function runInitExploration({
   catch { return { error: `Repository directory not found: ${projectDir || process.cwd()}` }; }
   const selected = String(platform || (url ? "web" : appId || apkPath ? "android" : "ios")).toLowerCase();
   if (!["ios", "android", "web"].includes(selected)) return { error: "platform must be ios|android|web" };
-  const mapPath = path.resolve(root, outDir, "ui-map.json");
+  const mapPath = path.resolve(root, projectArtifactDirectory(root, outDir), "ui-map.json");
   if (!isInsideDir(root, mapPath)) return { error: "UI Map output must remain inside the repository" };
 
   let resolvedTarget = "";
@@ -1832,7 +1833,7 @@ export async function startManagedWebTarget({ root, requestedTarget = "", timeou
     command = process.execPath;
     startArgs = [path.join(__dirname, "static-server.js"), startDir, String(port)];
   }
-  const logDir = path.join(autotapHome || os.tmpdir(), "init-runtime");
+  const logDir = path.join(tappHome || os.tmpdir(), "init-runtime");
   fs.mkdirSync(logDir, { recursive: true });
   const logPath = path.join(logDir, `web-${process.pid}-${Date.now()}.log`);
   const child = spawn(command, startArgs, {
@@ -1938,7 +1939,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         properties: {
           authToken: {
             type: "string",
-            description: "Required when AUTOTAP_MCP_TOKEN is set",
+            description: "Required when TAPP_MCP_TOKEN is set",
           },
           projectDir: { type: "string", description: "Repo/dir to search for the .xcworkspace/.xcodeproj (default: cwd)" },
           scheme: { type: "string", description: "Scheme to build (default: auto-detected)" },
@@ -1956,7 +1957,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         properties: {
           authToken: {
             type: "string",
-            description: "Required when AUTOTAP_MCP_TOKEN is set",
+            description: "Required when TAPP_MCP_TOKEN is set",
           },
           mode: {
             type: "string",
@@ -2075,7 +2076,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           appBundleId: { type: "string", description: "iOS: bundle id of the installed app to test, e.g. com.acme.app. Provide exactly one of appBundleId | url." },
           androidAppId: { type: "string", description: "Android: application id installed on a connected emulator/device, e.g. com.acme.app." },
           apkPath: { type: "string", description: "Android: optional APK to install before testing." },
@@ -2137,7 +2138,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           operation: { type: "string", enum: ["inspect", "write", "refresh", "explore"], default: "inspect" },
           projectDir: { type: "string", description: "Repo-relative project root; defaults to the MCP workspace root" },
           platform: { type: "string", enum: ["ios", "android", "web"], description: "Optional target filter" },
@@ -2152,7 +2153,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           testEmail: { type: "string", description: "Explore: actor/login email; never persisted in the model" },
           testPassword: { type: "string", description: "Explore: actor/login password; never persisted in the model" },
           maxContracts: { type: "integer", minimum: 1, maximum: 50, default: 15 },
-          outDir: { type: "string", description: "Repo-relative artifact directory; default .autotap" },
+          outDir: { type: "string", description: "Repo-relative artifact directory; default .tapp" },
         },
       },
     },
@@ -2160,11 +2161,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       name: "tapp_actor_config",
       title: "Inspect or configure named test actors without storing credential values",
       description:
-        "Manage the repository-native .autotap/project.json actor/session contract used by init, release-contract generation, and CI. `read` is inspect-only. `set` writes an explicit actor role, isolation/provisioning policy, and credential-name to environment-variable-name bindings. The tool never accepts, returns, or persists credential values and never overwrites an actor unless replace is explicit.",
+        "Manage the repository-native .tapp/project.json actor/session contract used by init, release-contract generation, and CI. `read` is inspect-only. `set` writes an explicit actor role, isolation/provisioning policy, and credential-name to environment-variable-name bindings. The tool never accepts, returns, or persists credential values and never overwrites an actor unless replace is explicit.",
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           operation: { type: "string", enum: ["read", "set"], default: "read" },
           projectDir: { type: "string", description: "Repo-relative project root; defaults to the MCP workspace root" },
           name: { type: "string", description: "Set: stable actor name" },
@@ -2180,14 +2181,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       name: "tapp_release_plan",
       title: "Inspect or explicitly review a Tapp release plan",
       description:
-        "Read the repository-native release plan, apply explicit approve/reject/defer decisions, generate grounded Task/contract drafts, deterministically validate drafts on a real target, or explicitly promote fully replay-validated drafts into reviewed repository-native artifacts. Review changes only decision metadata. Generation writes under .autotap/proposals, never overwrites, never invokes AI, and remains untrusted until real deterministic replay passes. Web validation can build/start/stop the detected managed target when url is omitted.",
+        "Read the repository-native release plan, apply explicit approve/reject/defer decisions, generate grounded Task/contract drafts, deterministically validate drafts on a real target, or explicitly promote fully replay-validated drafts into reviewed repository-native artifacts. Review changes only decision metadata. Generation writes under .tapp/proposals, never overwrites, never invokes AI, and remains untrusted until real deterministic replay passes. Web validation can build/start/stop the detected managed target when url is omitted.",
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           operation: { type: "string", enum: ["read", "review", "generate", "validate", "promote"], default: "read" },
-          planPath: { type: "string", description: "Repo-relative plan path; default .autotap/release-plan.json" },
-          projectDir: { type: "string", description: "Generate: repo-relative project root containing the scoped .autotap Task directories" },
+          planPath: { type: "string", description: "Repo-relative plan path; default .tapp/release-plan.json" },
+          projectDir: { type: "string", description: "Generate: repo-relative project root containing the scoped .tapp Task directories" },
           approve: { type: "array", items: { type: "string" }, description: "Plan item ids or names to approve" },
           reject: { type: "array", items: { type: "string" }, description: "Plan item ids or names to reject" },
           defer: { type: "array", items: { type: "string" }, description: "Plan item ids or names to defer" },
@@ -2211,14 +2212,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           operation: { type: "string", enum: ["inspect", "install", "baseline"], default: "inspect" },
           projectDir: { type: "string", description: "Repo-relative project root; defaults to the MCP workspace root" },
-          modelPath: { type: "string", description: "Repo-relative application model path; defaults to <projectDir>/.autotap/application-model.json" },
+          modelPath: { type: "string", description: "Repo-relative application model path; defaults to <projectDir>/.tapp/application-model.json" },
           actionRef: { type: "string", description: "GitHub Action reference owner/repository@release-tag-or-sha; defaults to the current Tapp release tag" },
           defaultBranch: { type: "string", default: "main" },
           workflowPath: { type: "string", description: "Install: project-relative output; default .github/workflows/tapp.yml" },
-          manifestPath: { type: "string", description: "Install: project-relative output; default .autotap/ci.json" },
+          manifestPath: { type: "string", description: "Install: project-relative output; default .tapp/ci.json" },
           allowUnresolved: { type: "boolean", default: false, description: "Permit writing a draft whose manifest names unresolved target configuration" },
           replace: { type: "boolean", default: false, description: "Explicitly replace an existing generated workflow/manifest or target baseline" },
           reportPath: { type: "string", description: "Baseline: repo-relative successful conclusive portable-gate JSON report" },
@@ -2237,10 +2238,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           operation: { type: "string", enum: ["read", "build", "diff"], default: "read" },
           captureId: { type: "string", description: "Read/build from this Tapp capture's ocqa-markers.txt/ui-map.json" },
-          mapPath: { type: "string", description: "Repo-relative UI Map path for read, or build output (default .autotap/ui-map.json)" },
+          mapPath: { type: "string", description: "Repo-relative UI Map path for read, or build output (default .tapp/ui-map.json)" },
           markersPath: { type: "string", description: "Repo-relative OCQA markers path for build when captureId is not supplied" },
           beforePath: { type: "string", description: "Repo-relative baseline UI Map for diff" },
           afterPath: { type: "string", description: "Repo-relative current UI Map for diff" },
@@ -2255,15 +2256,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       name: "tapp_task",
       title: "Inspect, validate, or compile a reusable deterministic Task",
       description:
-        "Work with repository-native compositional Tasks in .autotap/tasks. Tasks define inputs, outputs, pre/postconditions, platform implementations, and the UI Map states/transitions they cover. " +
+        "Work with repository-native compositional Tasks in .tapp/tasks. Tasks define inputs, outputs, pre/postconditions, platform implementations, and the UI Map states/transitions they cover. " +
         "Validation is deterministic and can ground selectors/coverage against ui-map.json. Compilation expands a Task into the shared keyless Flow contract with reviewable Task provenance; pass that returned flow to tapp_flow_run to replay it. No AI or API key is used.",
       inputSchema: {
         type: "object",
         required: ["taskPath"],
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           operation: { type: "string", enum: ["read", "validate", "compile"], default: "validate" },
-          taskPath: { type: "string", description: "Repo-relative .autotap/tasks/*.yml|json file" },
+          taskPath: { type: "string", description: "Repo-relative .tapp/tasks/*.yml|json file" },
           platform: { type: "string", enum: ["ios", "android", "web"], description: "Implementation to validate/compile" },
           inputs: { type: "object", additionalProperties: { type: "string" }, description: "Task inputs for compile. Secret inputs must be environment placeholders such as $TEST_PASSWORD, never plaintext." },
           mapPath: { type: "string", description: "Optional repo-relative UI Map v1 used to ground states, edges, and semantic controls" },
@@ -2276,15 +2277,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       name: "tapp_release_contract",
       title: "Inspect, validate, compile, or run a release contract",
       description:
-        "Work with repository-native TypeScript release contracts in .autotap/contracts. Contracts express business guarantees through reusable Tasks, named actors, exact/eventual expectations, criticality, policy, and UI Map coverage. " +
+        "Work with repository-native TypeScript release contracts in .tapp/contracts. Contracts express business guarantees through reusable Tasks, named actors, exact/eventual expectations, criticality, policy, and UI Map coverage. " +
         "Compilation targets the same deterministic Flow/Scenario evidence contract; ordinary run is keyless and never invokes a model. Multi-actor isolated replay is currently web-only.",
       inputSchema: {
         type: "object",
         required: ["contractPath"],
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           operation: { type: "string", enum: ["read", "validate", "compile", "run"], default: "validate" },
-          contractPath: { type: "string", description: "Repo-relative .autotap/contracts/*.contract.ts file" },
+          contractPath: { type: "string", description: "Repo-relative .tapp/contracts/*.contract.ts file" },
           platform: { type: "string", enum: ["ios", "android", "web"], description: "Target platform; optional when the contract declares exactly one" },
           mapPath: { type: "string", description: "Optional repo-relative UI Map v1 for coverage grounding" },
           updateMap: { type: "boolean", default: false, description: "Explicitly add the reviewed contract coverage to mapPath" },
@@ -2305,7 +2306,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           operation: { type: "string", enum: ["plan", "adopt"], default: "plan" },
           changedFiles: {
             type: "array", minItems: 1,
@@ -2326,10 +2327,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           },
           projectDir: { type: "string", description: "Repo-relative project root; defaults to the MCP workspace root" },
           platform: { type: "string", enum: ["ios", "android", "web"], description: "Optional platform filter" },
-          mapPath: { type: "string", description: "Project-relative UI Map; defaults to .autotap/ui-map.json" },
+          mapPath: { type: "string", description: "Project-relative UI Map; defaults to .tapp/ui-map.json" },
           prPlanPath: { type: "string", description: "Adopt: project-relative executed PR plan containing conclusive exploration evidence" },
           item: { type: "string", description: "Adopt: stable exploration target id whose reviewable proposal should be appended" },
-          releasePlanPath: { type: "string", description: "Adopt: project-relative target; defaults to .autotap/release-plan.json" },
+          releasePlanPath: { type: "string", description: "Adopt: project-relative target; defaults to .tapp/release-plan.json" },
         },
       },
     },
@@ -2350,13 +2351,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           flow: {
             type: "object",
             description:
               "Inline Flow: {name, app, steps:[...], vars?}. Example: {name:'login', app:'com.acme.app', steps:[{tap:'Sign In'}, {type:{field:'Email', value:'$TEST_EMAIL'}}, {tap:'Continue'}, {assert_screen:'Home'}]}",
           },
-          flowPath: { type: "string", description: "Alternative to `flow`: repo-relative path to a .yml/.json Flow (e.g. .autotap/flows/login.yml)" },
+          flowPath: { type: "string", description: "Alternative to `flow`: repo-relative path to a .yml/.json Flow (e.g. .tapp/flows/login.yml)" },
           platform: { type: "string", enum: ["ios", "web", "android"], description: "Overrides Flow platform detection" },
           appBundleId: { type: "string", description: "iOS: overrides the Flow's `app:` field" },
           androidAppId: { type: "string", description: "Android: overrides the Flow's `app:` field" },
@@ -2379,7 +2380,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           scenario: { type: "object", description: "Inline Scenario with {kind:'scenario', platform:'web', actors, steps, setup?, teardown?}" },
           scenarioPath: { type: "string", description: "Repo-relative path to a .yml/.json Scenario" },
           url: { type: "string", description: "Override the Scenario's web URL" },
@@ -2394,13 +2395,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         "Write a deterministic E2E Flow from a natural-language goal (e.g. 'sign in and open Settings'), " +
         "GROUNDED in the app's real screens so it can't invent steps. Tapp explores the app to build a " +
         "screen/control map (or reuses a recent run via captureId), then a model authors a Flow using only " +
-        "screens/controls that were actually observed. Saves it to .autotap/flows/<name>.yml and returns the " +
+        "screens/controls that were actually observed. Saves it to .tapp/flows/<name>.yml and returns the " +
         "YAML for review (optionally runs it). Needs a model backend (Tapp subscription token or " +
         "ANTHROPIC_API_KEY). Use this to bootstrap a test you then refine; use tapp_flow_run to replay it.",
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           goal: { type: "string", description: "What the test should do, in plain English (e.g. 'sign in with test creds and reach the dashboard')" },
           appBundleId: { type: "string", description: "Bundle id of the installed app to author against" },
           captureId: { type: "string", description: "Reuse this capture's grounding instead of exploring (from a prior run_qa, faster)" },
@@ -2418,13 +2419,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       description:
         "Save what you've done in the CURRENT interactive session as a reusable, deterministic Flow " +
         "(record-by-doing). Every successful tapp_session_act (tap/type/swipe/back) is recorded; this " +
-        "writes them to .autotap/flows/<name>.yml with wait_for steps auto-inserted on screen changes and a " +
+        "writes them to .tapp/flows/<name>.yml with wait_for steps auto-inserted on screen changes and a " +
         "final assert_screen checkpoint. Typed credentials are templated to $TEST_EMAIL/$TEST_PASSWORD so the " +
         "flow is shareable. The saved flow replays with tapp_flow_run. Do it once → it's a test.",
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           name: { type: "string", description: "Human name for the flow, e.g. 'Sign in and reach Home'" },
           addFinalAssertion: { type: "boolean", default: true, description: "Append assert_screen for the final screen as a checkpoint" },
           replace: { type: "boolean", default: false, description: "Explicitly replace a Flow with the same generated filename. Existing Flows are preserved by default." },
@@ -2442,7 +2443,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           appBundleId: { type: "string", description: "iOS bundle id of the installed app" },
           androidAppId: { type: "string", description: "Android application id of the installed app" },
           androidSerial: { type: "string", description: "Android adb device serial" },
@@ -2459,7 +2460,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           maxWidth: { type: "integer", minimum: 200, maximum: 1400, default: 700, description: "Max image width in px (downscaled to keep payload small)" },
         },
       },
@@ -2477,7 +2478,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           appBundleId: { type: "string", description: "iOS bundle id of the installed app" },
           androidAppId: { type: "string", description: "Android application id of the installed app" },
           apkPath: { type: "string", description: "Android APK to install before launch" },
@@ -2502,7 +2503,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           udid: { type: "string", description: "Simulator UDID (from tapp_list_simulators)" },
           name: { type: "string", description: "Simulator name, e.g. 'iPhone 16 Pro' (used if udid omitted)" },
         },
@@ -2518,7 +2519,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           project: { type: "string", description: "Absolute path to .xcodeproj (use this OR workspace)" },
           workspace: { type: "string", description: "Absolute path to .xcworkspace (use this OR project)" },
           scheme: { type: "string", description: "Scheme to build" },
@@ -2542,7 +2543,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           appBundleId: { type: "string", description: "Bundle id of the installed app to drive" },
           androidAppId: { type: "string", description: "Android application id to drive (alternative to appBundleId)" },
           apkPath: { type: "string", description: "Android APK to install before starting" },
@@ -2571,7 +2572,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" },
+          authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           action: { type: "string", enum: ["login", "tap", "type", "swipe", "back", "wait", "tree", "screenshot"] },
           email: { type: "string", description: "login: email/username to sign in with" },
           password: { type: "string", description: "login: password to sign in with" },
@@ -2592,7 +2593,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       description: "End the active interactive session (quits the app + harness). Always call this when done.",
       inputSchema: {
         type: "object",
-        properties: { authToken: { type: "string", description: "Required when AUTOTAP_MCP_TOKEN is set" } },
+        properties: { authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" } },
       },
     },
   ],
@@ -2908,7 +2909,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (maxContracts < 1 || maxContracts > 50) return errorResult("maxContracts must be between 1 and 50");
     const { initializeProductProject } = await import("./product-operations.js");
     try {
-      const outDir = isNonEmptyString(args.outDir) ? args.outDir.trim() : ".autotap";
+      const outDir = isNonEmptyString(args.outDir) ? args.outDir.trim() : ".tapp";
       const resolvedOut = path.resolve(projectDir, outDir);
       if (!isInsideDir(projectDir, resolvedOut)) return errorResult("outDir must be inside projectDir");
       const selectedPlatform = isNonEmptyString(args.platform) ? args.platform.trim().toLowerCase()
@@ -2979,7 +2980,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = String(args.operation || "read").toLowerCase();
     if (!["read", "review", "generate", "validate", "promote"].includes(operation)) return errorResult("operation must be read|review|generate|validate|promote");
-    const planPath = path.resolve(repoRoot, isNonEmptyString(args.planPath) ? args.planPath.trim() : ".autotap/release-plan.json");
+    const planPath = isNonEmptyString(args.planPath) ? path.resolve(repoRoot, args.planPath.trim()) : existingProjectArtifactPath(repoRoot, "release-plan.json");
     if (!isInsideDir(repoRoot, planPath)) return errorResult("planPath must be inside the repo");
     if (!fs.existsSync(planPath)) return errorResult("Release plan not found", { planPath });
     let plan;
@@ -3054,7 +3055,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (!["inspect", "install", "baseline"].includes(operation)) return errorResult("operation must be inspect|install|baseline");
     const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
     if (!isInsideDir(repoRoot, projectDir) || !fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) return errorResult("projectDir must be an existing directory inside the repo");
-    const modelPath = isNonEmptyString(args.modelPath) ? path.resolve(repoRoot, args.modelPath.trim()) : path.join(projectDir, ".autotap", "application-model.json");
+    const modelPath = isNonEmptyString(args.modelPath) ? path.resolve(repoRoot, args.modelPath.trim()) : existingProjectArtifactPath(projectDir, "application-model.json");
     if (!isInsideDir(projectDir, modelPath) || !fs.existsSync(modelPath)) return errorResult("Application model not found inside projectDir; run tapp_init first", { modelPath });
     let model;
     try { model = JSON.parse(fs.readFileSync(modelPath, "utf8")); }
@@ -3078,7 +3079,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const rendered = prepareProductCi({ projectDir, modelPath, actionRef, defaultBranch });
       if (operation === "inspect") return richResult(`🧩 CI plan — ${rendered.manifest.targets.length} target job(s) · ${rendered.manifest.unresolved.length} unresolved · read-only`, rendered);
       if (rendered.manifest.unresolved.length && !asBoolean(args.allowUnresolved)) return errorResult("CI workflow not installed because target configuration remains unresolved", { unresolved: rendered.manifest.unresolved, next: "Resolve the application model requirements or explicitly allow an inspect-only draft." });
-      const result = installProductCi({ projectDir, modelPath, actionRef, defaultBranch, workflowPath: isNonEmptyString(args.workflowPath) ? args.workflowPath.trim() : ".github/workflows/tapp.yml", manifestPath: isNonEmptyString(args.manifestPath) ? args.manifestPath.trim() : ".autotap/ci.json", replace: asBoolean(args.replace), allowUnresolved: asBoolean(args.allowUnresolved) });
+      const result = installProductCi({ projectDir, modelPath, actionRef, defaultBranch, workflowPath: isNonEmptyString(args.workflowPath) ? args.workflowPath.trim() : ".github/workflows/tapp.yml", manifestPath: isNonEmptyString(args.manifestPath) ? args.manifestPath.trim() : ".tapp/ci.json", replace: asBoolean(args.replace), allowUnresolved: asBoolean(args.allowUnresolved) });
       return richResult(`✅ Reviewable CI gate installed — ${result.manifest.targets.length} target job(s); no commit, push, branch protection, or GitHub resource was created`, result);
     } catch (error) { return errorResult("Could not prepare CI installation", { detail: error.message || String(error) }); }
   }
@@ -3109,7 +3110,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const markersPath = capture ? path.join(capture.path, "ocqa-markers.txt") : resolveRepoFile(args.markersPath);
       if (!markersPath) return errorResult("markersPath must be inside the repo, or provide captureId");
       if (!fs.existsSync(markersPath)) return errorResult("OCQA markers not found", { markersPath });
-      const outPath = resolveRepoFile(args.mapPath, path.join(".autotap", "ui-map.json"));
+      const outPath = isNonEmptyString(args.mapPath) ? resolveRepoFile(args.mapPath) : existingProjectArtifactPath(repoRoot, "ui-map.json");
       if (!outPath) return errorResult("mapPath must be inside the repo");
       try {
         const observed = buildUiMapFromMarkers({ markersPath, platform: args.platform || "ios", target: args.target || "", runId: capture?.id || "" });
@@ -3120,7 +3121,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       } catch (error) { return errorResult("Could not build UI Map", { detail: error.message || String(error) }); }
     }
     if (operation !== "read") return errorResult("operation must be read|build|diff");
-    const mapPath = capture ? path.join(capture.path, "ui-map.json") : resolveRepoFile(args.mapPath, path.join(".autotap", "ui-map.json"));
+    const mapPath = capture ? path.join(capture.path, "ui-map.json") : isNonEmptyString(args.mapPath) ? resolveRepoFile(args.mapPath) : existingProjectArtifactPath(repoRoot, "ui-map.json");
     if (!mapPath) return errorResult("mapPath must be inside the repo");
     if (!fs.existsSync(mapPath)) return errorResult("UI Map not found; run QA or operation=build first", { mapPath });
     try {
@@ -3450,7 +3451,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (!isNonEmptyString(args.goal)) return errorResult("goal is required");
     if (!isNonEmptyString(args.appBundleId)) return errorResult("appBundleId is required");
     const backend = resolveModelBackend();
-    if (!backend) return errorResult("AI-generate needs a model backend — set an Tapp subscription token (AUTOTAP_SUBSCRIPTION_TOKEN) or ANTHROPIC_API_KEY.");
+    if (!backend) return errorResult("AI-generate needs a model backend — set TAPP_SUBSCRIPTION_TOKEN or ANTHROPIC_API_KEY.");
     const bundleId = args.appBundleId.trim();
 
     // 1) Grounding: reuse a capture's markers, else explore the app to build a screen/control map.
@@ -3480,7 +3481,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const ungrounded = ungroundedScreens(parsed.steps, grounding);
     const flow = { name: args.name || parsed.name, app: bundleId, steps: parsed.steps };
     const slug = flow.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "generated-flow";
-    const dir = path.join(repoRoot, ".autotap", "flows");
+    const dir = path.join(repoRoot, ".tapp", "flows");
     fs.mkdirSync(dir, { recursive: true });
     const outPath = path.join(dir, `${slug}.yml`);
     const yamlRes = await runCommand("python3", [path.join(scriptsDir, "flow_lib.py"), "to-yaml", JSON.stringify(flow)], { cwd: repoRoot });

package/mcp-server/src/maintenance-proposal.js

@@ -125,16 +125,16 @@ export async function validateWebMaintenanceProposal({ proposal, projectDir, url
   if (!projectDir || !url) throw new Error("web maintenance validation requires projectDir and the running target URL");
   const root = fs.realpathSync(path.resolve(projectDir));
   const operation = proposal.operations[0];
-  const taskRoot = fs.realpathSync(path.join(root, ".autotap", "tasks"));
+  const taskRoot = fs.realpathSync(path.join(root, ".tapp", "tasks"));
   const sourceTask = fs.realpathSync(path.resolve(root, operation.taskPath));
   const sourceContract = fs.realpathSync(path.resolve(root, proposal.contractIntent.path));
-  if (!inside(taskRoot, sourceTask)) throw new Error("maintenance Task must be a regular reviewed file under .autotap/tasks");
+  if (!inside(taskRoot, sourceTask)) throw new Error("maintenance Task must be a regular reviewed file under .tapp/tasks");
   if (!inside(root, sourceContract)) throw new Error("maintenance contract must remain inside the project");
   if (digest(sourceTask) !== operation.taskSha256) throw new Error("Task digest changed after the proposal was created");
   if (digest(sourceContract) !== proposal.contractIntent.sha256) throw new Error("release-contract intent digest changed after the proposal was created");
 
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "tapp-maintenance-validation-"));
-  const tempTasks = path.join(tempRoot, ".autotap", "tasks");
+  const tempTasks = path.join(tempRoot, ".tapp", "tasks");
   const stem = String(proposal.contractIntent.name || "contract").replace(/[^A-Za-z0-9._-]/g, "-");
   const outputDir = evidenceDir ? path.resolve(evidenceDir, stem) : path.join(tempRoot, "evidence");
   const logPath = path.join(outputDir, "validation.log");
@@ -153,7 +153,7 @@ export async function validateWebMaintenanceProposal({ proposal, projectDir, url
     if (!(contract.setup || []).length || !(contract.teardown || []).length) {
       throw new Error("automatic disposable maintenance validation requires controlled contract setup and teardown");
     }
-    const pseudoContractPath = path.join(tempRoot, ".autotap", "contracts", path.basename(sourceContract));
+    const pseudoContractPath = path.join(tempRoot, ".tapp", "contracts", path.basename(sourceContract));
     const execution = compileReleaseContract(contract, { platform: "web", sourcePath: pseudoContractPath });
     const result = await runWebFlow({ flow: execution, url, logPath, screenshotDir: outputDir });
     const contractUnchanged = digest(sourceContract) === proposal.contractIntent.sha256;

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

@@ -8,6 +8,7 @@ import crypto from "node:crypto";
 import { loadReleaseContractFile } from "./release-contract.js";
 import { loadTaskRegistry } from "./task-runtime.js";
 import { replayableUiMapNavigation, semanticUiKey } from "./ui-map.js";
+import { existingProjectArtifactPath, isProjectArtifactDirectory } from "./project-paths.js";
 
 function posix(value) {
   return String(value || "").replaceAll("\\", "/").replace(/^\.\//, "").replace(/^\/+/, "");
@@ -28,8 +29,8 @@ export function sourcePathMatches(changedFile, ownershipPath) {
 function repoRootFor(sourcePath) {
   let current = path.dirname(path.resolve(sourcePath));
   while (current !== path.dirname(current)) {
-    if (path.basename(current) === ".autotap") return path.dirname(current);
-    if (fs.existsSync(path.join(current, ".autotap"))) return current;
+    if (isProjectArtifactDirectory(path.basename(current))) return path.dirname(current);
+    if (fs.existsSync(existingProjectArtifactPath(current))) return current;
     current = path.dirname(current);
   }
   return process.cwd();
@@ -403,11 +404,11 @@ function mergeGroundingEvidence(existing, incoming) {
   return merged;
 }
 
-export function adoptPrCoverageProposal({ projectDir, prPlanPath, item, releasePlanPath = ".autotap/release-plan.json" } = {}) {
+export function adoptPrCoverageProposal({ projectDir, prPlanPath, item, releasePlanPath = ".tapp/release-plan.json" } = {}) {
   const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
   const source = path.resolve(prPlanPath || "");
   if (!prPlanPath || !fs.existsSync(source)) throw new Error(`PR plan not found: ${source || "(missing path)"}`);
-  const targetPath = path.resolve(root, releasePlanPath);
+  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`);
   const prPlan = JSON.parse(fs.readFileSync(source, "utf8"));
@@ -423,7 +424,7 @@ export function adoptPrCoverageProposal({ projectDir, prPlanPath, item, releaseP
   const proposed = structuredClone(proposal.operation.item);
   if (proposed?.origin !== "deterministic-ui-map-proposal" || proposed?.decision !== "pending") throw new Error("Coverage proposal is not a pending UI-Map-grounded release-plan item");
   const ground = (proposed.groundedBy || []).find((entry) => entry.type === "ui-map-node");
-  const mapPath = path.join(root, ".autotap", "ui-map.json");
+  const mapPath = existingProjectArtifactPath(root, "ui-map.json");
   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");
@@ -583,7 +584,7 @@ export async function buildPrContractPlan({
     ...(Array.isArray(changedSymbolEvidence) ? changedSymbolEvidence : []),
   ]);
   const evidenceByFile = new Map(diffEvidence.map((item) => [item.file, item]));
-  const contractDir = path.join(root, ".autotap", "contracts");
+  const contractDir = existingProjectArtifactPath(root, "contracts");
   const discovered = discoverContracts && fs.existsSync(contractDir)
     ? fs.readdirSync(contractDir).filter((name) => /\.contract\.(?:ts|mts|mjs|js|json)$/i.test(name)).map((name) => path.join(contractDir, name)) : [];
   const files = [...new Set([...discovered, ...contractPaths.map((item) => path.resolve(root, item))])];
@@ -594,10 +595,10 @@ export async function buildPrContractPlan({
   }
 
   let tasks = new Map();
-  const registrySource = files[0] || path.join(root, ".autotap", "contracts", "contract.ts");
+  const registrySource = files[0] || existingProjectArtifactPath(root, "contracts", "contract.ts");
   try { tasks = loadTaskRegistry({ sourcePath: registrySource, projectDir: root }); } catch {}
   let map = null;
-  const resolvedMapPath = mapPath ? path.resolve(root, mapPath) : path.join(root, ".autotap", "ui-map.json");
+  const resolvedMapPath = mapPath ? path.resolve(root, mapPath) : existingProjectArtifactPath(root, "ui-map.json");
   if (fs.existsSync(resolvedMapPath)) map = JSON.parse(fs.readFileSync(resolvedMapPath, "utf8"));
 
   const impactedNodes = map ? map.nodes.filter((node) => matchedFiles(changes, node.sourcePaths || []).length) : [];

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

@@ -13,7 +13,7 @@ import { compileReleaseContract, loadReleaseContractFile } from "./release-contr
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
 function executionHome() {
-  return process.env.AUTOTAP_HOME || process.env.TAPP_HOME || path.join(os.homedir(), ".tapp");
+  return process.env.TAPP_HOME || process.env.AUTOTAP_HOME || path.join(os.homedir(), ".tapp");
 }
 
 function atomicJson(destination, value) {