@aarwitz/tapp 0.15.1 → 0.16.1

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/README.md

@@ -35,34 +35,22 @@ agent:  *tapp: builds, opens the app, navigates to Settings, screenshots it*
 agent:  "Done — and here it is working on the simulator: [screenshot]"
 ```
 
-## Quickstart
+## Quickstart for coding agents
 
 Requirements: **Node ≥ 18**. iOS needs **macOS + Xcode**; Android needs `adb` plus a connected
 emulator/device; web needs Playwright + Chromium.
 
-**Launch experience — browser Release Studio.** Open the source chooser from anywhere:
+From the app repository, let the agent see the current screen and then ask for a release verdict:
 
 ```bash
-npx -y @aarwitz/tapp app
+npx -y @aarwitz/tapp open   # builds/launches as needed; prints a screenshot path + screen summary
+npx -y @aarwitz/tapp qa     # explores the real app; prints verdict, findings, and evidence report
 ```
 
-Drag and drop a local repository folder or connect through your authenticated GitHub CLI and select
-an authorized repository. To work directly in an existing writable checkout, use `tapp app .`.
-The local, loopback-only workspace detects iOS, Android, and web targets. A single configured target
-builds and explores automatically; Tapp asks only when selection is ambiguous or configuration is
-genuinely missing. It renders the UI Map,
-supports release-contract review and keyless validation, records live semantic actions as committed
-Flows, and produces target-scoped gate, baseline, evidence, and CI artifacts. CLI, MCP, VS Code, and
-the GitHub Action use the same product/gate operations; the retained managed-runner prototype is
-being replaced by the future isolated SaaS worker boundary.
-
-**Zero config — get a verdict right now.** From your app's repo, one command. No server, no
-config file, no test code — you don't even need to know your bundle id:
-
-```bash
-cd YourApp
-npx -y @aarwitz/tapp qa    # finds your Xcode project → builds → installs on the simulator → explores → verdict
-```
+Claude Code can read the saved image with its file-reading tool; Codex can open it with
+`view_image`. The agent should report what the screenshot proves, preserve Tapp's exact
+`ready`/`caution`/`blocked` verdict, and link the HTML evidence report. No server, account, config
+file, test code, API key, or bundle id is required for this loop.
 
 The product, executable, and package leaf are all Tapp: npm distributes it as
 `@aarwitz/tapp`, while the installed command remains `tapp`.
@@ -90,9 +78,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.
@@ -124,6 +112,12 @@ npx -y @aarwitz/tapp install    # ~2 min, one time
 npx -y @aarwitz/tapp doctor     # verify Xcode / simulators / toolchain
 ```
 
+### Optional browser workspace
+
+`npx -y @aarwitz/tapp app .` opens a local Release Studio for people who want visual repository
+onboarding, release-plan review, and CI preparation. It is not required for the coding-agent
+`open`/`qa` workflow.
+
 ### MCP hookup (optional)
 
 The MCP server adds the two things a CLI can't do: **screenshots inline in your agent's
@@ -182,8 +176,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.
 
@@ -271,8 +265,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.
@@ -305,14 +299,14 @@ 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.
 
@@ -351,8 +345,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. Runtime configuration uses `TAPP_*` environment variables; deprecated
-aliases remain readable for compatibility.
+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

@@ -22,16 +22,16 @@ 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.
-// The old environment alias remains populated only for older helper integrations.
+// 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;
-if (!process.env.AUTOTAP_HOME) process.env.AUTOTAP_HOME = tappHome;
 fs.mkdirSync(tappHome, { recursive: true });
 
 const [, , command = "help", ...rest] = process.argv;
@@ -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`);
@@ -461,6 +461,27 @@ switch (command) {
     const { flags, positionals } = parseVerbArgs(rest);
     const engine = await engineImport();
     const platform = requestedPlatform(flags, positionals[0] || "");
+    if (platform === "web") {
+      const url = positionals[0] || "";
+      if (!/^https?:\/\//i.test(url)) {
+        console.error("❌ Web open needs an http(s) URL");
+        process.exit(2);
+      }
+      try {
+        const { inspectWebPage } = await import(path.join(packageRoot, "mcp-server", "src", "web-explorer.js"));
+        const snap = await inspectWebPage({ url, timeoutMs: Number(flags.timeout) * 1000 || 15_000 });
+        const out = typeof flags.out === "string" ? path.resolve(flags.out) : path.join(tappHome, "shots", `web-${Date.now()}.png`);
+        fs.mkdirSync(path.dirname(out), { recursive: true });
+        fs.writeFileSync(out, snap.image);
+        console.log(`🌐 Opened \`${snap.url}\`\n`);
+        console.log(engine.formatScreen(snap.screenTitle, snap.elements));
+        console.log(`\n📸 Screenshot: ${out}`);
+      } catch (error) {
+        console.error(`❌ ${error.message || String(error)}`);
+        process.exit(1);
+      }
+      break;
+    }
     if (platform === "android") {
       const target = androidTarget(flags, positionals[0] || "");
       const { AndroidDriver } = await import(path.join(packageRoot, "mcp-server", "src", "android-driver.js"));
@@ -504,6 +525,23 @@ switch (command) {
     const { flags, positionals } = parseVerbArgs(rest);
     const engine = await engineImport();
     const platform = requestedPlatform(flags, positionals[0] || "");
+    if (platform === "web") {
+      const url = positionals[0] || "";
+      if (!/^https?:\/\//i.test(url)) {
+        console.error("❌ Web tree needs an http(s) URL");
+        process.exit(2);
+      }
+      try {
+        const { inspectWebPage } = await import(path.join(packageRoot, "mcp-server", "src", "web-explorer.js"));
+        const snap = await inspectWebPage({ url, timeoutMs: Number(flags.timeout) * 1000 || 15_000, screenshot: false });
+        if (flags.json) console.log(JSON.stringify({ platform: "web", url: snap.url, screenTitle: snap.screenTitle, elements: snap.elements }, null, 2));
+        else console.log(engine.formatScreen(snap.screenTitle, snap.elements));
+      } catch (error) {
+        console.error(`❌ ${error.message || String(error)}`);
+        process.exit(1);
+      }
+      break;
+    }
     if (platform === "android") {
       const target = androidTarget(flags, positionals[0] || "");
       const { AndroidDriver } = await import(path.join(packageRoot, "mcp-server", "src", "android-driver.js"));
@@ -608,7 +646,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); }
@@ -741,7 +779,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 {
@@ -918,7 +956,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 +974,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 +997,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);
   }
 
@@ -1096,7 +1134,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 +1241,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 +1280,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,
         });
@@ -1317,21 +1355,9 @@ switch (command) {
     console.log(`tapp v${pkg.version} — ship with proof. Autonomous QA and deterministic Flows for iOS, Android, and web.
 
 Zero-config verbs (agents and humans can just run these — no server, no setup):
-  tapp app [repo]          Open the browser onboarding, contract-review, and release-evidence workspace
-                           (loopback-only; --no-open · --port PORT)
-  tapp init [repo]         Detect targets and write the application model + reviewable release plan
-                           (--explore builds/starts or connects, grounds the UI Map, then tears down)
-                           (--url URL · --platform PLATFORM · --dry-run · --refresh)
-  tapp actor list [repo]   Inspect named actors, sessions, provisioning, and secret env bindings
-  tapp actor set NAME      Configure an actor using environment-variable names only (never values)
-  tapp plan show [FILE]    Inspect the proposed/accepted release-contract plan
-  tapp plan review [FILE]  Explicitly approve, reject, or defer proposed plan items
-  tapp plan generate [FILE] Generate compile-checked, untrusted contract drafts from approved Tasks
-  tapp plan validate [FILE] Replay drafts on a real target; trust only after all platforms pass
-  tapp plan promote [FILE] Move fully validated drafts into reviewed Tasks/contracts + map coverage
+  tapp open [target]       Launch the app → screen summary + screenshot saved to a file
   tapp qa [target]         Autonomous QA → verdict + findings + evidence
                            (--platform ios|android|web · --app-id ID · --apk FILE · --actions N)
-  tapp open [target]       Launch the app → screen summary + screenshot saved to a file
   tapp tree [target]       Accessibility tree of the current screen (--json for every element)
   tapp flow run FILE       Replay a committed deterministic Flow (no AI/API key)
   tapp flow validate FILE  Validate a Flow without launching a target
@@ -1353,6 +1379,18 @@ Zero-config verbs (agents and humans can just run these — no server, no setup)
   tapp build [dir]         Build the iOS app in a repo for the simulator + install it (--scheme S)
   tapp apps                List apps installed on the booted simulator (with bundle ids)
   tapp report [captureId]  Open the HTML evidence page for a capture (default: latest)
+  tapp app [repo]          Optional local browser workspace for repository onboarding and review
+                           (loopback-only; --no-open · --port PORT)
+  tapp init [repo]         Detect targets and write the application model + reviewable release plan
+                           (--explore builds/starts or connects, grounds the UI Map, then tears down)
+                           (--url URL · --platform PLATFORM · --dry-run · --refresh)
+  tapp actor list [repo]   Inspect named actors, sessions, provisioning, and secret env bindings
+  tapp actor set NAME      Configure an actor using environment-variable names only (never values)
+  tapp plan show [FILE]    Inspect the proposed/accepted release-contract plan
+  tapp plan review [FILE]  Explicitly approve, reject, or defer proposed plan items
+  tapp plan generate [FILE] Generate compile-checked, untrusted contract drafts from approved Tasks
+  tapp plan validate [FILE] Replay drafts on a real target; trust only after all platforms pass
+  tapp plan promote [FILE] Move fully validated drafts into reviewed Tasks/contracts + map coverage
   tapp ci ...              Merge-blocking release gate — explore + flows + baseline diff (see: tapp ci --help)
   tapp ci install [repo]   Generate a reviewable target-aware GitHub workflow + CI manifest
 

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/mcp-server/src/application-model.js

@@ -8,6 +8,7 @@ import { credentialBindingsFromValue, readProjectConfig } from "./project-config
 import { applyReleaseContractCoverage, compileReleaseContract, loadReleaseContractFile, validateReleaseContractAgainstUiMap } from "./release-contract.js";
 import { applyTaskCoverage, loadTaskFile, validateTaskAgainstUiMap } from "./task-runtime.js";
 import { semanticUiKey } from "./ui-map.js";
+import { isProjectArtifactDirectory, projectArtifactDirectory } from "./project-paths.js";
 
 const SKIP = new Set([".git", ".build", ".gradle", ".next", ".swiftpm", "Pods", "Carthage", "DerivedData", "build", "dist", "node_modules", "vendor"]);
 
@@ -25,7 +26,7 @@ function walk(root, maxDepth = 4) {
     let entries;
     try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
     for (const entry of entries) {
-      if (SKIP.has(entry.name) || (entry.name.startsWith(".") && entry.name !== ".autotap")) continue;
+      if (SKIP.has(entry.name) || (entry.name.startsWith(".") && !isProjectArtifactDirectory(entry.name))) continue;
       const absolute = path.join(dir, entry.name);
       if (entry.isDirectory()) {
         directories.push(absolute);
@@ -124,7 +125,8 @@ function applyRuntimeTargetValidation(root, targets, validation) {
 }
 
 function persistedTargetValidations(root, outDir) {
-  const artifactDir = path.resolve(root, String(outDir || ".autotap"));
+  const requested = String(outDir || ".tapp");
+  const artifactDir = path.resolve(root, projectArtifactDirectory(root, requested));
   const relativeArtifactDir = path.relative(root, artifactDir);
   if (path.isAbsolute(relativeArtifactDir) || relativeArtifactDir === ".." || relativeArtifactDir.startsWith(`..${path.sep}`)) return [];
   const prior = readJson(path.join(artifactDir, "application-model.json"));
@@ -299,10 +301,11 @@ function uiMapTargetsTarget(map, target, targets) {
 }
 
 function loadTargetUiMaps(root, targets) {
-  const rootMap = loadUiMapAt(root, path.join(".autotap", "ui-map.json"));
+  const rootMap = loadUiMapAt(root, path.join(projectArtifactDirectory(root), "ui-map.json"));
   const records = targets.map((target) => {
     const scope = targetArtifactScope(target);
-    const expectedPath = posix(path.join(scope === "." ? "" : scope, ".autotap", "ui-map.json"));
+    const scopeRoot = path.join(root, scope === "." ? "" : scope);
+    const expectedPath = posix(path.join(scope === "." ? "" : scope, projectArtifactDirectory(scopeRoot), "ui-map.json"));
     let loaded = expectedPath === rootMap.summary.path ? rootMap : loadUiMapAt(root, expectedPath);
     if (!loaded.map && rootMap.map && (targets.length === 1 || uiMapTargetsTarget(rootMap.map, target, targets))) loaded = rootMap;
     return {
@@ -328,7 +331,7 @@ function loadTargetUiMaps(root, targets) {
   const prefixCoverage = unique.length > 1;
   const coverageValues = (field) => unique.flatMap((record) => (record.summary[field] || []).map((id) => prefixCoverage ? `${record.summary.targetId}:${id}` : id));
   const summary = {
-    path: unique.length === 1 ? unique[0].summary.path : ".autotap/ui-map.json",
+    path: unique.length === 1 ? unique[0].summary.path : ".tapp/ui-map.json",
     paths: unique.map((record) => record.summary.path).sort(),
     status: allObserved ? "observed" : someObserved ? "partial" : someInconclusive ? "inconclusive" : "missing",
     nodeCount: unique.reduce((total, record) => total + record.summary.nodeCount, 0),
@@ -348,14 +351,14 @@ function loadTargetUiMaps(root, targets) {
 
 function artifactScope(root, file) {
   const parts = relative(root, file).split("/");
-  const index = parts.indexOf(".autotap");
+  const index = parts.findIndex(isProjectArtifactDirectory);
   return index > 0 ? parts.slice(0, index).join("/") : ".";
 }
 
 function artifactFiles(root, inventory, kind, pattern) {
   return inventory.files.filter((file) => {
     const parts = relative(root, file).split("/");
-    const index = parts.indexOf(".autotap");
+    const index = parts.findIndex(isProjectArtifactDirectory);
     return index >= 0 && parts[index + 1] === kind && pattern.test(path.basename(file));
   }).sort();
 }
@@ -421,7 +424,7 @@ function applicationName(root, targets) {
   return pkg?.name || (targets.length === 1 ? targets[0].name : path.basename(root));
 }
 
-export async function inspectApplicationRepository({ projectDir, ownedUrl = "", platform = "", targetValidation = null, outDir = ".autotap" } = {}) {
+export async function inspectApplicationRepository({ projectDir, ownedUrl = "", platform = "", targetValidation = null, outDir = ".tapp" } = {}) {
   const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
   const inventory = walk(root);
   let targets = [
@@ -550,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 .autotap/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 tapp 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." });
@@ -925,7 +928,7 @@ function invalidateGeneratedTaskFiles(root, plan) {
   for (const record of plan.generation?.generatedTasks || []) {
     if (!record.path) continue;
     const absolute = path.resolve(root, record.path);
-    const proposalRoot = path.join(root, ".autotap", "proposals", "tasks");
+    const proposalRoot = path.join(root, projectArtifactDirectory(root), "proposals", "tasks");
     if (!isInsideRoot(proposalRoot, absolute) || !fs.existsSync(absolute)) continue;
     const task = readJson(absolute);
     if (!task || task.generation?.origin !== "deterministic-ui-map") continue;
@@ -937,8 +940,8 @@ function invalidateGeneratedTaskFiles(root, plan) {
   }
 }
 
-export function writeInitArtifacts({ root, model, plan, outDir = ".autotap", refresh = false, invalidateValidation = false } = {}) {
-  const directory = path.resolve(root, outDir);
+export function writeInitArtifacts({ root, model, plan, outDir = ".tapp", refresh = false, invalidateValidation = false } = {}) {
+  const directory = path.resolve(root, projectArtifactDirectory(root, outDir));
   const modelPath = path.join(directory, "application-model.json");
   const planPath = path.join(directory, "release-plan.json");
   if (!refresh && (fs.existsSync(modelPath) || fs.existsSync(planPath))) throw new Error(`Init artifacts already exist under ${relative(root, directory)}; inspect them or rerun with --refresh to preserve reviewed decisions while updating evidence`);
@@ -1069,7 +1072,7 @@ function generatedTaskName(node, entryOnly, occupied, identity) {
   return `${base}${crypto.createHash("sha256").update(identity).digest("hex").slice(0, 6)}`;
 }
 
-function prepareMapBackedItem(item, map, existingTasks, taskDrafts, { targetId = "", mapPath = ".autotap/ui-map.json" } = {}) {
+function prepareMapBackedItem(item, map, existingTasks, taskDrafts, { targetId = "", mapPath = ".tapp/ui-map.json" } = {}) {
   const ground = (item.groundedBy || []).find((entry) => entry.type === "ui-map-node");
   if (!ground) throw new Error("Approved UI-only proposal is not grounded by a UI Map node");
   const nodes = new Map((map.nodes || []).map((node) => [node.id, node]));
@@ -1168,7 +1171,7 @@ function writeGeneratedTaskDrafts(root, taskDrafts) {
   for (const draft of [...taskDrafts.values()].sort((a, b) => a.name.localeCompare(b.name))) {
     const scopeRoot = path.resolve(root, draft.scope === "." || !draft.scope ? "" : draft.scope);
     if (!isInsideRoot(root, scopeRoot)) throw new Error(`Generated Task scope escapes repository: ${draft.scope}`);
-    const output = path.join(scopeRoot, ".autotap", "proposals", "tasks", `${kebab(draft.name)}.task.json`);
+    const output = path.join(scopeRoot, projectArtifactDirectory(scopeRoot), "proposals", "tasks", `${kebab(draft.name)}.task.json`);
     const definition = {
       kind: "task", version: 1, name: draft.name, description: draft.description,
       ...(Object.keys(draft.inputs || {}).length ? { inputs: draft.inputs } : {}),
@@ -1189,7 +1192,7 @@ function writeGeneratedTaskDrafts(root, taskDrafts) {
     }
     try {
       const task = loadTaskFile(output);
-      const mapPath = path.resolve(root, draft.mapPath || ".autotap/ui-map.json");
+      const mapPath = path.resolve(root, draft.mapPath || ".tapp/ui-map.json");
       if (!isInsideRoot(root, mapPath)) throw new Error(`Generated Task UI Map escapes repository: ${draft.mapPath}`);
       const map = readJson(mapPath);
       if (!map || map.schemaVersion !== 1) throw new Error(`Generated Task UI Map is missing or invalid: ${draft.mapPath}`);
@@ -1304,7 +1307,7 @@ export async function generateApprovedContractProposals(plan, { projectDir } = {
     let prepared = item;
     if (item.origin === "deterministic-ui-map-proposal") {
       const grounding = (item.groundedBy || []).find((entry) => entry.type === "ui-map-node");
-      const mapPath = grounding?.mapPath || ".autotap/ui-map.json";
+      const mapPath = grounding?.mapPath || ".tapp/ui-map.json";
       const absoluteMapPath = path.resolve(root, mapPath);
       const itemMap = isInsideRoot(root, absoluteMapPath) ? readJson(absoluteMapPath) : null;
       if (!itemMap || itemMap.schemaVersion !== 1) {
@@ -1329,7 +1332,7 @@ export async function generateApprovedContractProposals(plan, { projectDir } = {
     if (!prepared) continue;
     const scopeRoot = path.resolve(root, item.scope === "." || !item.scope ? "" : item.scope);
     if (scopeRoot !== root && !scopeRoot.startsWith(root + path.sep)) throw new Error(`Plan scope escapes repository: ${item.scope}`);
-    const output = path.join(scopeRoot, ".autotap", "proposals", "contracts", `${kebab(item.name)}.contract.ts`);
+    const output = path.join(scopeRoot, projectArtifactDirectory(scopeRoot), "proposals", "contracts", `${kebab(item.name)}.contract.ts`);
     const source = draftContractSource(prepared, projectConfiguration.config || {});
     if (fs.existsSync(output) && fs.readFileSync(output, "utf8") !== source) throw new Error(`Draft contract already exists with different content and was not overwritten: ${relative(root, output)}`);
     const created = !fs.existsSync(output);
@@ -1412,13 +1415,13 @@ export function recordContractProposalValidation(plan, { id = "", name = "", pla
 export function recordGeneratedTaskProposalValidation({ projectDir, item, platform, evidence = "", detail = "" } = {}) {
   if (!["ios", "android", "web"].includes(platform)) throw new Error("platform must be ios|android|web");
   const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
-  const proposalMarker = `${path.sep}.autotap${path.sep}proposals${path.sep}tasks${path.sep}`;
-  const reviewedMarker = `${path.sep}.autotap${path.sep}tasks${path.sep}`;
+  const proposalMarkers = [".tapp", ".autotap"].map((directory) => `${path.sep}${directory}${path.sep}proposals${path.sep}tasks${path.sep}`);
+  const reviewedMarkers = [".tapp", ".autotap"].map((directory) => `${path.sep}${directory}${path.sep}tasks${path.sep}`);
   const updated = [];
   for (const taskPath of item?.generation?.taskPaths || []) {
     const absolute = path.resolve(root, taskPath);
-    const proposed = isInsideRoot(root, absolute) && absolute.includes(proposalMarker);
-    const reviewed = isInsideRoot(root, absolute) && absolute.includes(reviewedMarker) && !absolute.includes(proposalMarker);
+    const proposed = isInsideRoot(root, absolute) && proposalMarkers.some((marker) => absolute.includes(marker));
+    const reviewed = isInsideRoot(root, absolute) && reviewedMarkers.some((marker) => absolute.includes(marker)) && !proposed;
     if ((!proposed && !reviewed) || !fs.existsSync(absolute)) throw new Error(`Generated Task is missing or outside Tapp Task directories: ${taskPath}`);
     const task = readJson(absolute);
     if (!task || task.kind !== "task" || task.generation?.origin !== "deterministic-ui-map") throw new Error(`Generated Task draft has invalid provenance: ${taskPath}`);
@@ -1458,10 +1461,13 @@ export function mergeGeneratedTaskProposalValidation(plan, updates = []) {
 }
 
 function promotedDestination(root, source, kind) {
-  const marker = `${path.sep}.autotap${path.sep}proposals${path.sep}${kind}${path.sep}`;
+  const marker = [".tapp", ".autotap"]
+    .map((directory) => `${path.sep}${directory}${path.sep}proposals${path.sep}${kind}${path.sep}`)
+    .find((candidate) => source.includes(candidate));
+  if (!marker) throw new Error(`Proposal ${kind.slice(0, -1)} is outside .tapp/proposals/${kind}: ${relative(root, source)}`);
   const index = source.indexOf(marker);
-  if (index < 0) throw new Error(`Proposal ${kind.slice(0, -1)} is outside .autotap/proposals/${kind}: ${relative(root, source)}`);
-  const destination = `${source.slice(0, index)}${path.sep}.autotap${path.sep}${kind}${path.sep}${source.slice(index + marker.length)}`;
+  const directory = marker.split(path.sep).filter(Boolean)[0];
+  const destination = `${source.slice(0, index)}${path.sep}${directory}${path.sep}${kind}${path.sep}${source.slice(index + marker.length)}`;
   if (!isInsideRoot(root, destination)) throw new Error(`Promotion destination escapes repository: ${destination}`);
   return destination;
 }
@@ -1480,7 +1486,7 @@ export async function promoteValidatedProposals(plan, { projectDir, ids = [] } =
 
   const mapCache = new Map();
   const mapForItem = (item) => {
-    const relativeMapPath = item.generation?.mapPath || (item.groundedBy || []).find((entry) => entry.type === "ui-map-node")?.mapPath || ".autotap/ui-map.json";
+    const relativeMapPath = item.generation?.mapPath || (item.groundedBy || []).find((entry) => entry.type === "ui-map-node")?.mapPath || ".tapp/ui-map.json";
     const absolute = path.resolve(root, relativeMapPath);
     if (!isInsideRoot(root, absolute)) throw new Error(`UI Map for '${item.name}' escapes the repository: ${relativeMapPath}`);
     if (!mapCache.has(absolute)) {
@@ -1499,7 +1505,7 @@ export async function promoteValidatedProposals(plan, { projectDir, ids = [] } =
     for (const taskPath of item.generation.taskPaths || []) {
       const source = path.resolve(root, taskPath);
       if (!fs.existsSync(source)) throw new Error(`Generated Task is missing: ${taskPath}`);
-      if (!String(source).includes(`${path.sep}.autotap${path.sep}proposals${path.sep}tasks${path.sep}`)) continue;
+      if (![".tapp", ".autotap"].some((directory) => String(source).includes(`${path.sep}${directory}${path.sep}proposals${path.sep}tasks${path.sep}`))) continue;
       const destination = promotedDestination(root, source, "tasks");
       moves.set(source, destination);
       let task = taskRecords.get(source);