@aarwitz/tapp 0.15.0 → 0.16.0

package/AGENTS.md

@@ -18,7 +18,7 @@ npx -y @aarwitz/tapp shot            # screenshot the booted sim → file path (
 npx -y @aarwitz/tapp apps            # what's installed on the simulator, with bundle ids
 npx -y @aarwitz/tapp build [dir]     # build the app in an Xcode repo + install it (≈ tapp_build)
 npx -y @aarwitz/tapp qa app.apk --platform android --app-id com.acme.app
-npx -y @aarwitz/tapp flow run .autotap/flows/smoke.yml  # committed, keyless E2E replay
+npx -y @aarwitz/tapp flow run .tapp/flows/smoke.yml  # committed, keyless E2E replay
 ```
 
 **Seeing the screen, per client:** if you can read image files into your context (Claude
@@ -92,13 +92,13 @@ Returns `{verdict, confidence, headline, screensExplored, actionsPerformed, find
 
 ## Flows (deterministic E2E tests)
 
-Flow YAML is repository-native test code. Commit it under `.autotap/flows/`; CI can replay it
+Flow YAML is repository-native test code. Commit it under `.tapp/flows/`; CI can replay it
 without a coding agent, model, subscription, or API key. AI generation and `assert_ai` are optional.
 
 - **Record:** every successful `session_act` is recorded. After driving a flow, call
-  `tapp_flow_save { name: "checkout" }` → writes `.autotap/flows/checkout.yml` with waits and
+  `tapp_flow_save { name: "checkout" }` → writes `.tapp/flows/checkout.yml` with waits and
   a final screen assertion auto-inserted; typed credentials are templated to `$TEST_EMAIL`/`$TEST_PASSWORD`.
-- **Replay:** `tapp_flow_run { flowPath: ".autotap/flows/checkout.yml" }` — exact steps,
+- **Replay:** `tapp_flow_run { flowPath: ".tapp/flows/checkout.yml" }` — exact steps,
   deterministic assertions, same result every time. A failed assertion is a finding.
 - **Generate:** `tapp_flow_generate { goal: "log in and add the first item to cart" }` —
   grounded in the app's actually-explored screens, so it can't invent steps.

package/Harness/OCQAHarness/AppDelegate.swift

@@ -8,7 +8,7 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
         let vc = UIViewController()
         vc.view.backgroundColor = .black
         let label = UILabel()
-        label.text = "AutoTap Harness"
+        label.text = "Tapp Harness"
         label.textColor = .white
         label.textAlignment = .center
         label.frame = vc.view.bounds

package/Harness/OCQAHarness.xcodeproj/project.pbxproj

@@ -166,7 +166,7 @@
         CODE_SIGN_STYLE = Automatic;
         DEVELOPMENT_TEAM = "";
         INFOPLIST_FILE = OCQAHarness/Info.plist;
-        PRODUCT_BUNDLE_IDENTIFIER = ai.autotap.harness;
+        PRODUCT_BUNDLE_IDENTIFIER = io.github.aarwitz.tapp.harness;
         PRODUCT_NAME = "$(TARGET_NAME)";
         SWIFT_VERSION = 5.0;
         TARGETED_DEVICE_FAMILY = "1,2";
@@ -186,7 +186,7 @@
         CODE_SIGN_STYLE = Automatic;
         DEVELOPMENT_TEAM = "";
         INFOPLIST_FILE = OCQAHarnessUITests/Info.plist;
-        PRODUCT_BUNDLE_IDENTIFIER = ai.autotap.harness.uitests;
+        PRODUCT_BUNDLE_IDENTIFIER = io.github.aarwitz.tapp.harness.uitests;
         PRODUCT_NAME = "$(TARGET_NAME)";
         SWIFT_VERSION = 5.0;
         TARGETED_DEVICE_FAMILY = "1,2";

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -670,7 +670,7 @@ class ExplorerTests: XCTestCase {
 
     /// Replays an explicit, config-driven login flow (OCQA_LOGIN_STEPS) before exploration — for the
     /// custom login UIs the heuristic preamble can't parse, which are the #1 reason a real app stays
-    /// invisible to AutoTap. Steps are a JSON array of {action: type|tap|wait, target: <id-or-label>,
+    /// invisible to Tapp. Steps are a JSON array of {action: type|tap|wait, target: <id-or-label>,
     /// value?: <text; "$TEST_EMAIL"/"$TEST_PASSWORD" substituted from stored creds>, timeoutMs?}.
     /// Returns true if any step ran (so the caller skips the heuristic preamble). Tolerant: a failed
     /// step is logged but doesn't abort — exploration still proceeds, and the coverage eval reveals
@@ -1320,7 +1320,7 @@ class ExplorerTests: XCTestCase {
                     // so it surfaces here at the next tree read rather than at the early crash check.
                     // Report it against the action that led here instead of breaking silently. (Real:
                     // Wikipedia's WMFCaptchaViewController.refreshImage assertionFailure crashes the
-                    // app during login — a genuine production crash AutoTap must surface.)
+                    // app during login — a genuine production crash Tapp must surface.)
                     if app.state != .runningForeground {
                         let where_ = pendingTransitionFrom?.title ?? "the previous screen"
                         let crashKey = "crash-async:\(where_)"

package/Harness/generate-harness-xcodeproj.rb

@@ -182,7 +182,7 @@ pbxproj = <<~PBX
         CODE_SIGN_STYLE = Automatic;
         DEVELOPMENT_TEAM = "";
         INFOPLIST_FILE = OCQAHarness/Info.plist;
-        PRODUCT_BUNDLE_IDENTIFIER = ai.autotap.harness;
+        PRODUCT_BUNDLE_IDENTIFIER = io.github.aarwitz.tapp.harness;
         PRODUCT_NAME = "$(TARGET_NAME)";
         SWIFT_VERSION = 5.0;
         TARGETED_DEVICE_FAMILY = "1,2";
@@ -202,7 +202,7 @@ pbxproj = <<~PBX
         CODE_SIGN_STYLE = Automatic;
         DEVELOPMENT_TEAM = "";
         INFOPLIST_FILE = OCQAHarnessUITests/Info.plist;
-        PRODUCT_BUNDLE_IDENTIFIER = ai.autotap.harness.uitests;
+        PRODUCT_BUNDLE_IDENTIFIER = io.github.aarwitz.tapp.harness.uitests;
         PRODUCT_NAME = "$(TARGET_NAME)";
         SWIFT_VERSION = 5.0;
         TARGETED_DEVICE_FAMILY = "1,2";
@@ -249,6 +249,6 @@ SCHEME
 File.write("#{scheme_dir}/OCQAHarnessUITests.xcscheme", scheme)
 
 puts "✅ Generated OCQAHarness.xcodeproj"
-puts "   Host app: ai.autotap.harness"
+puts "   Host app: io.github.aarwitz.tapp.harness"
 puts "   Test target: OCQAHarnessUITests"
 puts "   Platform: iOS 16.0+"

package/README.md

@@ -65,8 +65,7 @@ npx -y @aarwitz/tapp qa    # finds your Xcode project → builds → installs on
 ```
 
 The product, executable, and package leaf are all Tapp: npm distributes it as
-`@aarwitz/tapp`, while the installed command remains `tapp`. Existing `npx runtapp ...`
-and `npx tapp-mcp ...` configurations remain supported as deprecated compatibility paths.
+`@aarwitz/tapp`, while the installed command remains `tapp`.
 
 To bootstrap maintained release infrastructure, preview the repository model and grounded plan
 before Tapp writes anything:
@@ -91,9 +90,9 @@ npx -y @aarwitz/tapp ci install .
 ```
 
 The baseline command writes only after autonomous QA and every selected deterministic suite pass
-conclusively. It stores `.autotap/baselines/<platform>/<target-id>.json`; the generated workflow
+conclusively. It stores `.tapp/baselines/<platform>/<target-id>.json`; the generated workflow
 uses that exact target identity so two apps on the same platform never share a baseline. `ci
-install` writes `.github/workflows/tapp.yml` plus `.autotap/ci.json`, refuses unresolved build
+install` writes `.github/workflows/tapp.yml` plus `.tapp/ci.json`, refuses unresolved build
 configuration and existing-file collisions, and never commits, pushes, enables branch protection,
 or creates GitHub resources. Review and pin the generated Tapp release reference to its immutable
 commit SHA before production.
@@ -183,8 +182,8 @@ Then ask your agent:
 
 Full agent playbook: [AGENTS.md](./AGENTS.md) — ships inside the package so agents can read it too.
 Application-model and import contract: [`docs/application-model.md`](docs/application-model.md).
-The desktop Coverage view reads the same `.autotap/application-model.json`,
-`.autotap/release-plan.json`, and `.autotap/ui-map.json`, including explicit proposal review; it
+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
 does not maintain a separate product model. Map nodes identify both the real launch entry and the
 deterministic per-platform navigation root used for bounded changed-surface replay.
 
@@ -272,8 +271,8 @@ The first successful, conclusive run on `main` seeds a repository-scoped Actions
 90-day baseline artifact. Both are keyed by platform and stable application-model target id. Pull requests automatically restore it and fail only on **new**
 high/critical findings or broken Flows—not pre-existing debt. No baseline commit or PAT is required.
 If you prefer a reviewed, durable baseline, run `tapp baseline create` and commit the generated
-`.autotap/baselines/<platform>/<target-id>.json`; `tapp ci install` wires its explicit path into the
-corresponding job. The legacy `.autotap/baseline.json` is still recognized. Automatic baseline restore and the PR comment need `actions: read` and
+`.tapp/baselines/<platform>/<target-id>.json`; `tapp ci install` wires its explicit path into the
+corresponding job. The legacy `.tapp/baseline.json` is still recognized. Automatic baseline restore and the PR comment need `actions: read` and
 `pull-requests: write` as shown above. Secrets are unavailable to workflows from forks, so
 auth-gated apps should either use a non-secret UI-testing launch argument or skip the gate for
 untrusted forks.
@@ -292,7 +291,7 @@ npx -y @aarwitz/tapp ci --app path/to/MyApp.app \
 ```
 
 See the self-test at
-[.github/workflows/autotap-gate-example.yml](.github/workflows/autotap-gate-example.yml) for
+[.github/workflows/tapp-gate-example.yml](.github/workflows/tapp-gate-example.yml) for
 Flows, auth inputs, and other controls. GitHub-hosted iOS runs require a macOS runner; the first
 run also builds the XCUITest harness, so budget roughly 5–10 minutes depending on app size.
 
@@ -306,19 +305,19 @@ or accept a prebuilt one:
     android-app-id: com.acme.app
     android-project: android
     android-task: :app:assembleDebug
-    flows: android/.autotap/flows/*.yml
+    flows: android/.tapp/flows/*.yml
 ```
 
 For web, pass `platform: web` plus `web-target:` and Tapp uses the application model to run its
 lockfile-backed install/build, start a detected package script or read-only static server, wait for
 readiness, gate it, and stop it even on failure. Pass `url:` instead for an already-running owned
 environment. Add
-`scenarios: .autotap/scenarios/*.yml` to gate isolated cross-account journeys; see
+`scenarios: .tapp/scenarios/*.yml` to gate isolated cross-account journeys; see
 [`docs/scenarios.md`](docs/scenarios.md). Automatic
 baselines are isolated by platform and target, so two same-platform apps are never compared.
 
-**The hosted service at `app.runtapp.com` is under development and is not currently offered for
-customer repositories.** Do not upload private code or credentials to an old preview. The retained
+**The hosted service is under development and is not currently offered for customer repositories.**
+Do not upload private code or credentials to an old preview. The retained
 cloud prototype is not the production SaaS boundary. Use the local Release Studio and the portable
 GitHub Action in infrastructure you control until the new account, tenant authorization, private
 evidence, and isolated-worker boundary passes security review.
@@ -352,8 +351,11 @@ verdict calculation run entirely locally — no telemetry, nothing phones home.
 features are explicit: finding enrichment requires `TAPP_ENABLE_REMOTE_AI=1` (an ambient
 API key alone never changes data handling), and AI flow generation / `assert_ai` only run
 when you invoke them; these send selected metadata (screen names, finding titles) to your
-configured model provider. Env vars: `TAPP_*` preferred; `AUTOTAP_*` accepted as deprecated
-aliases.
+configured model provider. Runtime configuration uses `TAPP_*` environment variables. Repository
+artifacts live under `.tapp/`, and desktop run configuration uses `.tapp.yml`. Existing
+`.autotap/`, `.autotap.yml`, and `AUTOTAP_*` inputs remain readable as migration fallbacks; when
+both names exist, Tapp uses the canonical one. Rename the old directory/config in your next
+reviewed repository change—no secrets or evidence formats need to be rewritten.
 
 Committed Flow replay, recording a driven session, autonomous exploration, exact assertions,
 regression comparison, and CI gating require **no API key and no coding agent at runtime**. AI is

package/bin/tapp.js

@@ -16,23 +16,23 @@
 //
 // All writable output (captures, harness build cache) goes to ~/.tapp (override
 // with TAPP_HOME). The package directory itself is never written to.
-// (Internally exported as AUTOTAP_HOME — the env name the bundled scripts read.)
 
 import { spawnSync, spawn } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { existingProjectArtifactPath, isProjectArtifactDirectory } from "../mcp-server/src/project-paths.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, "..");
 const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
 
 // Redirect all writable output away from the (possibly read-only) package dir.
-if (!process.env.AUTOTAP_HOME) {
-  process.env.AUTOTAP_HOME = process.env.TAPP_HOME || path.join(os.homedir(), ".tapp");
-}
-fs.mkdirSync(process.env.AUTOTAP_HOME, { recursive: true });
+// The old environment alias remains a read-only fallback for older integrations.
+const tappHome = (process.env.TAPP_HOME || process.env.AUTOTAP_HOME || path.join(os.homedir(), ".tapp")).trim();
+process.env.TAPP_HOME = tappHome;
+fs.mkdirSync(tappHome, { recursive: true });
 
 const [, , command = "help", ...rest] = process.argv;
 
@@ -88,7 +88,7 @@ function bootBestSimulator(preferredName = "iPhone 16 Pro") {
 }
 
 function harnessXctestrun() {
-  const dir = path.join(process.env.AUTOTAP_HOME, "harness-derived", "Build", "Products");
+  const dir = path.join(tappHome, "harness-derived", "Build", "Products");
   try {
     const found = fs.readdirSync(dir).find((f) => f.endsWith(".xctestrun"));
     return found ? path.join(dir, found) : null;
@@ -171,7 +171,7 @@ function androidTarget(flags, target = "") {
 }
 
 function saveShot(img, outFlag, name) {
-  const out = outFlag || path.join(process.env.AUTOTAP_HOME, "shots", name);
+  const out = outFlag || path.join(tappHome, "shots", name);
   fs.mkdirSync(path.dirname(out), { recursive: true });
   fs.writeFileSync(out, Buffer.from(img.data, "base64"));
   return out;
@@ -221,7 +221,7 @@ switch (command) {
       console.error("❌ --explore writes grounded UI Map evidence and cannot be combined with --dry-run");
       process.exit(2);
     }
-    const outDir = typeof flags["out-dir"] === "string" ? flags["out-dir"] : ".autotap";
+    const outDir = typeof flags["out-dir"] === "string" ? flags["out-dir"] : ".tapp";
     const artifactDir = path.resolve(projectDir, outDir);
     if (!artifactDir.startsWith(projectDir + path.sep) && artifactDir !== projectDir) {
       console.error("❌ --out-dir must remain inside the repository");
@@ -292,7 +292,7 @@ switch (command) {
   case "plan": {
     const { flags, positionals } = parseVerbArgs(rest);
     const verb = positionals[0] || "show";
-    const planPath = path.resolve(positionals[1] || ".autotap/release-plan.json");
+    const planPath = positionals[1] ? path.resolve(positionals[1]) : existingProjectArtifactPath(process.cwd(), "release-plan.json");
     if (!fs.existsSync(planPath)) {
       console.error(`❌ Release plan not found: ${planPath}`);
       process.exit(2);
@@ -366,7 +366,7 @@ switch (command) {
       break;
     }
     if (verb !== "review") {
-      console.error("usage: tapp plan show [.autotap/release-plan.json]\n       tapp plan review [.autotap/release-plan.json] --approve name[,name] --reject name[,name] --defer name[,name]\n       tapp plan generate [.autotap/release-plan.json] [--project-dir DIR]\n       tapp plan validate [.autotap/release-plan.json] --project-dir DIR --platform web [--url URL] [--target NAME|PATH]\n       tapp plan promote [.autotap/release-plan.json] --project-dir DIR [--item name[,name]]");
+      console.error("usage: tapp plan show [.tapp/release-plan.json]\n       tapp plan review [.tapp/release-plan.json] --approve name[,name] --reject name[,name] --defer name[,name]\n       tapp plan generate [.tapp/release-plan.json] [--project-dir DIR]\n       tapp plan validate [.tapp/release-plan.json] --project-dir DIR --platform web [--url URL] [--target NAME|PATH]\n       tapp plan promote [.tapp/release-plan.json] --project-dir DIR [--item name[,name]]");
       process.exit(2);
     }
     const list = (value) => typeof value === "string" ? value.split(",").map((item) => item.trim()).filter(Boolean) : [];
@@ -377,7 +377,7 @@ switch (command) {
     }
     const { reviewProductPlan } = await import(path.join(packageRoot, "mcp-server", "src", "product-operations.js"));
     const reviewProjectDir = typeof flags["project-dir"] === "string" ? path.resolve(flags["project-dir"])
-      : path.basename(path.dirname(planPath)) === ".autotap" ? path.dirname(path.dirname(planPath)) : path.dirname(planPath);
+      : isProjectArtifactDirectory(path.basename(path.dirname(planPath))) ? path.dirname(path.dirname(planPath)) : path.dirname(planPath);
     try { plan = reviewProductPlan({ projectDir: reviewProjectDir, planPath, ...decisions }).plan; }
     catch (error) { console.error(`❌ Could not review release plan: ${error.message || String(error)}`); process.exit(2); }
     console.log(`✅ Release plan updated — ${plan.items.filter((item) => ["approved", "accepted"].includes(item.decision)).length} accepted/approved · ${plan.items.filter((item) => item.decision === "rejected").length} rejected · ${plan.items.filter((item) => item.decision === "pending").length} pending`);
@@ -472,7 +472,7 @@ switch (command) {
       await driver.forceStop();
       console.log(`🚀 Launched \`${target.appId}\` (Android)\n`);
       console.log(engine.formatScreen(snap.screenTitle, snap.elements));
-      const out = typeof flags.out === "string" ? flags.out : path.join(process.env.AUTOTAP_HOME, "shots", `${target.appId}-${Date.now()}.png`);
+      const out = typeof flags.out === "string" ? flags.out : path.join(tappHome, "shots", `${target.appId}-${Date.now()}.png`);
       fs.mkdirSync(path.dirname(out), { recursive: true });
       fs.writeFileSync(out, data);
       console.log(`\n📸 Screenshot: ${out}`);
@@ -608,7 +608,7 @@ switch (command) {
     const verb = positionals[0] || "validate";
     const taskPath = positionals[1] ? path.resolve(positionals[1]) : "";
     if (!["validate", "compile", "run"].includes(verb) || !taskPath) {
-      console.error("usage: tapp task validate <task.yml> [--platform ios|android|web] [--map .autotap/ui-map.json]\n       tapp task compile <task.yml> --platform PLATFORM [--inputs '{\"name\":\"value\"}'] [--out compiled.json]\n       tapp task run <task.yml> --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID] [--inputs JSON]");
+      console.error("usage: tapp task validate <task.yml> [--platform ios|android|web] [--map .tapp/ui-map.json]\n       tapp task compile <task.yml> --platform PLATFORM [--inputs '{\"name\":\"value\"}'] [--out compiled.json]\n       tapp task run <task.yml> --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID] [--inputs JSON]");
       process.exit(2);
     }
     if (!fs.existsSync(taskPath)) { console.error(`❌ Task not found: ${taskPath}`); process.exit(2); }
@@ -663,7 +663,7 @@ switch (command) {
       url: typeof flags.url === "string" ? flags.url : task.url || "",
       reset: task.reset || "launch", vars: compiled.vars, steps: compiled.steps, taskPlan: compiled.plan,
     };
-    const out = path.resolve(typeof flags.out === "string" ? flags.out : path.join(process.env.AUTOTAP_HOME, "tasks", `${task.name}-${process.pid}-${Date.now()}.json`));
+    const out = path.resolve(typeof flags.out === "string" ? flags.out : path.join(tappHome, "tasks", `${task.name}-${process.pid}-${Date.now()}.json`));
     fs.mkdirSync(path.dirname(out), { recursive: true });
     fs.writeFileSync(out, JSON.stringify(flow, null, 2) + "\n");
     if (verb === "compile") {
@@ -712,8 +712,8 @@ switch (command) {
       break;
     }
     const token = `${process.pid}-${Date.now()}`;
-    const flowLog = path.join(process.env.AUTOTAP_HOME, "flows", `${token}.log`);
-    const evidenceDir = path.join(process.env.AUTOTAP_HOME, "captures", `flow-${platform}-${token}`);
+    const flowLog = path.join(tappHome, "flows", `${token}.log`);
+    const evidenceDir = path.join(tappHome, "captures", `flow-${platform}-${token}`);
     fs.mkdirSync(path.dirname(flowLog), { recursive: true });
     const env = { ...process.env, FLOW_LOG: flowLog, TAPP_FLOW_EVIDENCE_DIR: evidenceDir };
     if (typeof flags.email === "string") env.OCQA_TEST_EMAIL = flags.email;
@@ -741,7 +741,7 @@ switch (command) {
     const verb = positionals[0] || "validate";
     const contractPath = positionals[1] ? path.resolve(positionals[1]) : "";
     if (!["validate", "compile", "run"].includes(verb) || !contractPath) {
-      console.error("usage: tapp contract validate <name.contract.ts> [--platform ios|android|web] [--map .autotap/ui-map.json]\n       tapp contract compile <name.contract.ts> --platform PLATFORM [--out compiled.json]\n       tapp contract run <name.contract.ts> --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID]");
+      console.error("usage: tapp contract validate <name.contract.ts> [--platform ios|android|web] [--map .tapp/ui-map.json]\n       tapp contract compile <name.contract.ts> --platform PLATFORM [--out compiled.json]\n       tapp contract run <name.contract.ts> --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID]");
       process.exit(2);
     }
     const {
@@ -779,7 +779,7 @@ switch (command) {
     let compiled;
     try { compiled = compileReleaseContract(contract, { platform, sourcePath: contractPath }); }
     catch (error) { console.error(`❌ Could not compile Release Contract: ${error.message}`); process.exit(2); }
-    const out = path.resolve(typeof flags.out === "string" ? flags.out : path.join(process.env.AUTOTAP_HOME, "contracts", `${contract.name}-${process.pid}-${Date.now()}.json`));
+    const out = path.resolve(typeof flags.out === "string" ? flags.out : path.join(tappHome, "contracts", `${contract.name}-${process.pid}-${Date.now()}.json`));
     fs.mkdirSync(path.dirname(out), { recursive: true });
     fs.writeFileSync(out, JSON.stringify(compiled, null, 2) + "\n");
     if (verb === "compile") {
@@ -893,8 +893,8 @@ switch (command) {
       break;
     }
     const token = `${process.pid}-${Date.now()}`;
-    const flowLog = path.join(process.env.AUTOTAP_HOME, "scenarios", `${token}.log`);
-    const evidenceDir = path.join(process.env.AUTOTAP_HOME, "captures", `scenario-web-${token}`);
+    const flowLog = path.join(tappHome, "scenarios", `${token}.log`);
+    const evidenceDir = path.join(tappHome, "captures", `scenario-web-${token}`);
     const env = { ...process.env, FLOW_LOG: flowLog, TAPP_FLOW_EVIDENCE_DIR: evidenceDir };
     const url = typeof flags.url === "string" ? flags.url : scenario.url || scenario.app || "";
     const result = spawnSync(process.execPath, [path.join(packageRoot, "scripts", "run-web-scenario.js"), absolute, url], { stdio: "inherit", env });
@@ -918,7 +918,7 @@ switch (command) {
         console.error("❌ --platform must be ios|android|web");
         process.exit(2);
       }
-      const out = path.resolve(typeof flags.out === "string" ? flags.out : path.join(".autotap", "ui-map.json"));
+      const out = path.resolve(typeof flags.out === "string" ? flags.out : path.join(".tapp", "ui-map.json"));
       const observed = buildUiMapFromMarkers({
         markersPath,
         platform,
@@ -936,7 +936,7 @@ switch (command) {
       break;
     }
     if (verb === "inspect") {
-      const mapPath = path.resolve(positionals[1] || path.join(".autotap", "ui-map.json"));
+      const mapPath = positionals[1] ? path.resolve(positionals[1]) : existingProjectArtifactPath(process.cwd(), "ui-map.json");
       if (!fs.existsSync(mapPath)) { console.error(`❌ UI Map not found: ${mapPath}`); process.exit(2); }
       const map = JSON.parse(fs.readFileSync(mapPath, "utf8"));
       const errors = validateUiMap(map);
@@ -959,7 +959,7 @@ switch (command) {
       if (!diff.comparableFullSweep && (diff.notObservedNodes.length || diff.notObservedEdges.length)) console.log("ℹ️  Absence is not labeled a regression because the runs were not declared comparable full sweeps.");
       process.exit(diff.lostReachability.length || diff.lostTransitions.length ? 1 : 0);
     }
-    console.error("usage: tapp map build <ocqa-markers.txt> [--platform ios|android|web] [--out .autotap/ui-map.json]\n       tapp map inspect [ui-map.json]\n       tapp map diff <before.json> <after.json> [--comparable]");
+    console.error("usage: tapp map build <ocqa-markers.txt> [--platform ios|android|web] [--out .tapp/ui-map.json]\n       tapp map inspect [ui-map.json]\n       tapp map diff <before.json> <after.json> [--comparable]");
     process.exit(2);
   }
 
@@ -1007,7 +1007,7 @@ switch (command) {
       console.log("  ⬜ Web — install Playwright in the app workspace: npm install -D playwright && npx playwright install chromium");
     }
 
-    console.log(`\n  Home: ${process.env.AUTOTAP_HOME}`);
+    console.log(`\n  Home: ${tappHome}`);
     console.log(healthy ? "\nReady. Add to your agent:  claude mcp add tapp -- npx -y @aarwitz/tapp mcp" : "\nFix the ❌ items above, then re-run: tapp doctor");
     process.exit(healthy ? 0 : 1);
   }
@@ -1096,7 +1096,7 @@ switch (command) {
       process.exit(2);
     }
     const projectDir = fs.realpathSync(path.resolve(positionals[1] || (typeof flags["project-dir"] === "string" ? flags["project-dir"] : process.cwd())));
-    const modelPath = path.resolve(projectDir, typeof flags.model === "string" ? flags.model : path.join(".autotap", "application-model.json"));
+    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.`);
       process.exit(2);
@@ -1203,7 +1203,7 @@ switch (command) {
       let projectDir;
       try { projectDir = fs.realpathSync(path.resolve(positionals[0] || (typeof flags["project-dir"] === "string" ? flags["project-dir"] : process.cwd()))); }
       catch { console.error(`❌ Repository directory not found: ${positionals[0] || flags["project-dir"] || process.cwd()}`); process.exit(2); }
-      const modelPath = path.resolve(projectDir, typeof flags.model === "string" ? flags.model : path.join(".autotap", "application-model.json"));
+      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.`);
         process.exit(2);
@@ -1242,7 +1242,7 @@ switch (command) {
           actionRef,
           defaultBranch: typeof flags["default-branch"] === "string" ? flags["default-branch"] : "main",
           workflowPath: typeof flags.out === "string" ? flags.out : ".github/workflows/tapp.yml",
-          manifestPath: typeof flags.manifest === "string" ? flags.manifest : ".autotap/ci.json",
+          manifestPath: typeof flags.manifest === "string" ? flags.manifest : ".tapp/ci.json",
           replace: flags.replace === true,
           allowUnresolved: flags["allow-unresolved"] === true,
         });
@@ -1284,7 +1284,7 @@ switch (command) {
 
   case "report": {
     // Regenerate + open the HTML evidence page for a capture (default: the latest).
-    const capturesDir = path.join(process.env.AUTOTAP_HOME, "captures");
+    const capturesDir = path.join(tappHome, "captures");
     const repoCaptures = path.join(packageRoot, "captures");
     const roots = [capturesDir, repoCaptures].filter((d) => fs.existsSync(d));
     const runs = roots

package/browser/app.js

@@ -471,7 +471,7 @@ async function entriesFromDrop(event) {
 }
 
 // The webkitdirectory input (and some drop implementations) silently exclude hidden
-// entries, which destroys committed .autotap/ config. The File System Access picker
+// entries, which destroys committed .tapp/ config. The File System Access picker
 // enumerates hidden files, so it is preferred wherever it exists.
 async function entriesFromDirectoryHandle(handle, prefix = "") {
   const entries = [];
@@ -526,7 +526,7 @@ async function uploadRepository(name, entries, { hiddenComplete = false } = {})
     $("#operation-progress-bar").style.width = "100%";
     const hasHiddenEntries = entries.some((entry) => entry.path.split("/").some((part) => part.startsWith(".")));
     if (!hiddenComplete && !hasHiddenEntries) {
-      toast("Imported, but no hidden files (like .autotap/) came through — this browser's folder picker skips them. Committed Tapp config was not uploaded.", true);
+      toast("Imported, but no hidden files (like .tapp/) came through — this browser's folder picker skips them. Committed Tapp config was not uploaded.", true);
     } else {
       toast("Repository imported into an isolated Tapp workspace");
     }

package/browser/index.html

@@ -41,7 +41,7 @@
         <div class="source-icon">↥</div>
         <p class="eyebrow">CLOUD COPY</p>
         <h2>Upload a project folder</h2>
-        <p>Upload an isolated working copy from this computer. Committed hidden config (like <code>.autotap/</code>) is included; dependency and build output folders are skipped.</p>
+        <p>Upload an isolated working copy from this computer. Committed hidden config (like <code>.tapp/</code>) is included; dependency and build output folders are skipped.</p>
         <button class="primary" id="browse-folder">Browse folder</button>
         <input id="folder-input" type="file" webkitdirectory multiple hidden>
         <small>For direct edits to an existing checkout, start with <code>tapp app /path/to/repo</code>.</small>

package/docs/BROWSER-PRODUCT.md

@@ -39,7 +39,7 @@ in the local process/filesystem. This is a local trust boundary, not hosted mult
 11. **Install CI** by previewing and writing a reviewable repository patch. Tapp does not commit,
     push, create GitHub secrets, or enable branch protection.
 
-Successful semantic actions can be saved in `.autotap/flows/`; credential values are templated to
+Successful semantic actions can be saved in `.tapp/flows/`; credential values are templated to
 environment references. Long-lived repository artifacts store binding names, not resolved secret
 values.
 
@@ -62,7 +62,7 @@ intent.
 
 ## Hosted relationship
 
-`app.runtapp.com` will present the same product journey through a different adapter: application
+The future hosted application will present the same product journey through a different adapter: application
 accounts/organizations, GitHub App repository authorization, private storage, a durable queue, and
 isolated managed workers. It cannot reuse the loopback session, local `gh` authority, filesystem
 boundary, or in-memory ownership assumptions.

package/docs/PRODUCT-ENGINE.md

@@ -51,7 +51,7 @@ Current convergence:
   installation call the same operations;
 - the GitHub Action and `runProductGate` call the same portable gate and evidence protocol;
 - VS Code remains a thin MCP client;
-- desktop reads the same `.autotap` artifacts but still has legacy import/build orchestration. It is
+- desktop reads the same `.tapp` artifacts but still has legacy import/build orchestration. It is
   retained, not the launch UX, until that orchestration is removed;
 - `cloud/runner` is retained prototype evidence for exact checkout, versioned operation envelopes,
   leases, and cleanup. It is not the production hosted adapter or an adequate arbitrary-customer
@@ -60,10 +60,10 @@ Current convergence:
 
 ## Canonical repository protocol
 
-New product behavior writes only `.autotap/`:
+New product behavior writes only `.tapp/`:
 
 ```text
-.autotap/
+.tapp/
   project.json              # actors, env binding names, controlled lifecycle; never secret values
   application-model.json    # detected/observed/declared product facts
   ui-map.json               # grounded screen/action/transition graph
@@ -74,9 +74,10 @@ New product behavior writes only `.autotap/`:
   ci.json                   # generated CI installation manifest
 ```
 
-`.autotap.yml` and `.tapp.yml` are legacy compatibility inputs, not parallel sources of product
-truth. Do not add a fourth configuration format. Migration readers may normalize old input into the
-canonical model; only an explicit reviewed operation may write new repository artifacts.
+`.tapp.yml` is the canonical run configuration. Existing `.autotap.yml`, `.autotap/`, and
+`AUTOTAP_*` inputs remain readable during migration, but new examples and output use the Tapp names.
+Do not add another configuration format. Migration readers may normalize old input into the canonical
+model; only an explicit reviewed operation may write new repository artifacts.
 
 ## Anti-duplication rules
 

package/docs/application-model.md

@@ -3,9 +3,9 @@
 `tapp init` is the deterministic import, exploration, and planning entrypoint of Tapp's customer
 journey. It turns a repository into three platform-neutral, repository-native artifacts:
 
-- `.autotap/ui-map.json` — observed UI states, controls, and transitions from real exploration;
-- `.autotap/application-model.json` — what Tapp can support with evidence;
-- `.autotap/release-plan.json` — the compact set of committed and proposed business guarantees a
+- `.tapp/ui-map.json` — observed UI states, controls, and transitions from real exploration;
+- `.tapp/application-model.json` — what Tapp can support with evidence;
+- `.tapp/release-plan.json` — the compact set of committed and proposed business guarantees a
   customer must review before generation.
 
 Plain `tapp init` performs source/artifact inspection only. `tapp init --explore` additionally uses
@@ -73,7 +73,7 @@ tapp actor list .
 tapp init . --refresh
 ```
 
-This writes `.autotap/project.json`. The file contains roles, `default`/`isolated` session policy,
+This writes `.tapp/project.json`. The file contains roles, `default`/`isolated` session policy,
 provisioning mode, same-origin lifecycle declarations, and environment-variable *names*. The CLI
 and MCP `tapp_actor_config` reject credential values and refuse to replace an actor without an
 explicit `--replace`/`replace: true`. Contracts refer to `$ALICE_EMAIL`-style placeholders. Tapp
@@ -144,24 +144,24 @@ and the real-surface validation required before it can be trusted.
 ## Explicit review
 
 ```bash
-tapp plan show .autotap/release-plan.json
-tapp plan review .autotap/release-plan.json \
+tapp plan show .tapp/release-plan.json
+tapp plan review .tapp/release-plan.json \
   --approve signInWorks,checkoutWorks \
   --reject marketingPageReachable \
   --defer adminAuditWorks
 
-# Only after review: generate grounded Task + contract drafts under .autotap/proposals/.
-tapp plan generate .autotap/release-plan.json --project-dir .
+# Only after review: generate grounded Task + contract drafts under .tapp/proposals/.
+tapp plan generate .tapp/release-plan.json --project-dir .
 
 # Replay the draft on the real target and attach evidence to the plan.
 # Omit --url to build/start/stop the detected managed browser target.
-tapp plan validate .autotap/release-plan.json --project-dir . --platform web
+tapp plan validate .tapp/release-plan.json --project-dir . --platform web
 # Or connect to an already-running owned environment.
-tapp plan validate .autotap/release-plan.json --project-dir . \
+tapp plan validate .tapp/release-plan.json --project-dir . \
   --platform web --url http://127.0.0.1:3000
 
 # Explicitly accept only fully validated drafts into canonical reviewed locations.
-tapp plan promote .autotap/release-plan.json --project-dir . \
+tapp plan promote .tapp/release-plan.json --project-dir . \
   --item checkoutWorks
 ```
 
@@ -181,23 +181,18 @@ The macOS desktop Coverage experience reads these same files. Its **Application*
 detected targets, actors, capabilities, journeys, Tasks, contracts, and exact remediation. Its
 **Release Plan** tab writes explicit approve/reject/defer decisions atomically into the canonical
 plan while preserving fields from newer engine versions; committed contract intent is not editable
-through these proposal controls. Flow Map merges the repository `.autotap/ui-map.json` with current
+through these proposal controls. Flow Map merges the repository `.tapp/ui-map.json` with current
 run evidence instead of building a separate desktop-only graph.
 
-Schema compatibility can be rehearsed headlessly after building the desktop app:
-
-```bash
-AutoTap.app/Contents/MacOS/AutoTap --verify-artifacts /path/to/repository \
-  --out /tmp/tapp-desktop-artifacts.json
-```
+Schema compatibility is exercised by the repository's protocol tests and retained desktop reader.
 
 `plan generate` handles only explicitly approved proposals. Grounded cross-actor proposals preserve
 actor-attributed Task calls, captured output variables, bounded eventual assertions, and the
 reviewed project lifecycle, then compile through the isolated Scenario executor. Existing
 Task-backed proposals compose those reviewed Tasks. For UI-Map-only proposals, it finds an observed path from each platform's
 recorded entry state, deduplicates shared semantic transitions into compositional Task drafts under
-`.autotap/proposals/tasks/`, grounds every Task in exact node/edge ids, and writes the contract draft
-under `.autotap/proposals/contracts/`. Proposal Tasks are visible only to proposal contracts; an
+`.tapp/proposals/tasks/`, grounds every Task in exact node/edge ids, and writes the contract draft
+under `.tapp/proposals/contracts/`. Proposal Tasks are visible only to proposal contracts; an
 ordinary committed contract or CI glob cannot silently consume one.
 
 Generation blocks when entry-state evidence is missing, the target is unreachable, an observed
@@ -205,7 +200,7 @@ action cannot be represented deterministically, or platform paths require incomp
 composition. It never overwrites a draft, statically compiles each declared platform, and marks all
 outputs untrusted. Missing non-secret Task inputs stay blocked until the plan has explicit bindings;
 standard email/password secrets remain placeholders. Successful grounding and compilation are not
-real-surface evidence and never promote drafts into `.autotap/tasks` or `.autotap/contracts`.
+real-surface evidence and never promote drafts into `.tapp/tasks` or `.tapp/contracts`.
 
 `plan validate` invokes the ordinary deterministic contract executor and records pass/fail evidence
 per declared platform. A multi-platform draft remains only partially validated until every declared
@@ -214,8 +209,8 @@ substitution or automatic assertion update.
 
 `plan promote` is the explicit acceptance boundary. It refuses any contract or generated Task that
 has not passed every declared platform, preflights every destination, never overwrites a reviewed
-artifact, moves accepted files from `.autotap/proposals/{tasks,contracts}` into
-`.autotap/{tasks,contracts}`, and applies their exact node/edge coverage to the canonical UI Map.
+artifact, moves accepted files from `.tapp/proposals/{tasks,contracts}` into
+`.tapp/{tasks,contracts}`, and applies their exact node/edge coverage to the canonical UI Map.
 Shared Task paths in still-unpromoted proposals are rewritten to the canonical file. Promotion does
 not commit, push, or install CI; the resulting repository patch remains reviewable by the customer.
 
@@ -237,7 +232,7 @@ tapp ci install . --action-ref aarwitz/tapp@v0.13.1
 
 Baseline creation rejects non-gate JSON, missing or mismatched target identity, platform mismatch,
 failed Flows/Scenarios/contracts, `blocked`, and `inconclusive`. It writes atomically to
-`.autotap/baselines/<platform>/<target-id>.json` and requires `--replace` to supersede reviewed
+`.tapp/baselines/<platform>/<target-id>.json` and requires `--replace` to supersede reviewed
 evidence. Capture-local paths are replaced with portable `tapp-capture:` references before the
 repository artifact is written. The gate also checks baseline platform and target identity before
 comparing findings. On iOS, the same validated launch arguments and string-valued launch
@@ -245,7 +240,7 @@ environment are passed to autonomous exploration and deterministic Flow/contract
 JSON or unsupported value types fail before execution rather than silently testing different app
 configurations.
 
-CI installation writes `.github/workflows/tapp.yml` and `.autotap/ci.json`, never overwrites by
+CI installation writes `.github/workflows/tapp.yml` and `.tapp/ci.json`, never overwrites by
 default, and refuses unresolved iOS schemes, Android ids, browser lockfiles, or runtimes. The
 workflow uses exact contract paths, maps each actor environment binding to a same-named GitHub
 Secret, uses the first/default actor for autonomous-login inputs, preserves the remaining bindings