@aarwitz/tapp 0.16.0 → 0.16.2

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`.
@@ -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

package/bin/tapp.js

@@ -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"));
@@ -1008,7 +1046,9 @@ switch (command) {
     }
 
     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");
+    console.log(healthy
+      ? "\nReady. Start with:\n  npx -y @aarwitz/tapp open [target]\n  npx -y @aarwitz/tapp qa [target]"
+      : "\nFix the ❌ items above, then re-run: tapp doctor");
     process.exit(healthy ? 0 : 1);
   }
 
@@ -1317,21 +1357,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 +1381,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/mcp-server/src/web-explorer.js

@@ -97,6 +97,65 @@ export function webBrowserLaunchOptions(environment = process.env) {
   };
 }
 
+// Focused one-screen inspection for the agent-facing `tapp open <url>` and `tapp tree <url>`
+// commands. This deliberately does no exploration or judgment; it opens exactly one page,
+// captures the visible semantic controls, and optionally takes one screenshot.
+export async function inspectWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, screenshot = true }) {
+  let target;
+  try { target = new URL(url); }
+  catch { throw new Error("Web inspection needs a valid http(s) URL"); }
+  if (!/^https?:$/.test(target.protocol)) throw new Error("Web inspection needs a valid http(s) URL");
+
+  const { chromium } = await loadPlaywright();
+  const browser = await chromium.launch(webBrowserLaunchOptions());
+  try {
+    const context = await browser.newContext({ viewport: { width: 1280, height: 900 } });
+    const page = await context.newPage();
+    const boundedTimeout = Math.max(1000, Math.min(60_000, Number(timeoutMs) || NAV_TIMEOUT_MS));
+    page.setDefaultTimeout(boundedTimeout);
+    const response = await page.goto(target.href, { waitUntil: "domcontentloaded", timeout: boundedTimeout });
+    if (response && response.status() >= 400) throw new Error(`Could not open ${target.href}: HTTP ${response.status()}`);
+    await page.waitForTimeout(SETTLE_MS);
+    const observed = await page.evaluate(() => {
+      const visible = (element) => element.offsetParent !== null;
+      const controls = [...document.querySelectorAll("button, a[href], input, textarea, select, [role=button], [role=tab], [role=checkbox], [role=switch]")]
+        .filter((element) => element.type !== "hidden" && visible(element))
+        .slice(0, 80)
+        .map((element) => {
+          const tag = element.tagName.toLowerCase();
+          const field = ["input", "textarea", "select"].includes(tag);
+          const secure = element.type === "password";
+          const role = element.getAttribute("role") || (tag === "a" ? "link" : tag === "button" ? "button" : "");
+          const label = (element.labels?.[0]?.textContent || element.getAttribute("aria-label") || element.textContent || element.placeholder || element.name || element.id || "").trim().slice(0, 120);
+          return {
+            type: field ? (secure ? "SecureTextField" : "TextField") : "Button",
+            role,
+            label,
+            identifier: element.id || element.getAttribute("data-testid") || element.getAttribute("aria-label") || "",
+            isEnabled: !element.disabled && element.getAttribute("aria-disabled") !== "true",
+            hittable: true,
+            secure,
+          };
+        })
+        .filter((control) => control.label || control.identifier);
+      return {
+        heading: document.querySelector("h1")?.textContent?.trim() || "",
+        title: document.title.trim(),
+        controls,
+      };
+    });
+    const image = screenshot ? await page.screenshot({ type: "png" }) : null;
+    return {
+      url: page.url(),
+      screenTitle: webScreenTitle(observed, target.pathname || target.href),
+      elements: observed.controls,
+      image,
+    };
+  } finally {
+    await browser.close().catch(() => {});
+  }
+}
+
 export function normalizeWebSeedRoutes(url, routes, limit = 5) {
   const origin = new URL(url);
   const boundedLimit = Math.max(0, Math.min(10, Number(limit) || 0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "mcpName": "io.github.aarwitz/tapp",
   "description": "Release contracts, autonomous QA, and evidence-backed CI gates for iOS, Android, and web.",
   "license": "MIT",
@@ -87,7 +87,7 @@
     "mobile"
   ],
   "scripts": {
-    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/cloud-runner.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/action.test.js tests/package-surface.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js",
+    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/action.test.js tests/package-surface.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js",
     "test:browser-journey": "node --test tests/browser-journey.test.js",
     "test:browser-native": "TAPP_RUN_NATIVE_BROWSER=1 node --test tests/browser-native-journey.test.js"
   }

package/docs/BROWSER-PRODUCT.md

@@ -1,72 +0,0 @@
-# Browser Release Studio
-
-Status: current local-product contract as of 2026-08-08.
-
-The browser is Tapp's primary customer workflow. Web is also one application target beside iOS and
-Android; it is not a separate QA product. CLI, MCP, VS Code, the Action, desktop, and future managed
-SaaS adapt the shared product operations described in [`PRODUCT-ENGINE.md`](PRODUCT-ENGINE.md).
-
-## Start locally
-
-```bash
-npx -y @aarwitz/tapp app
-```
-
-Tapp prints an authenticated one-time launch URL and opens it in the default browser. Use
-`--no-open` when copying the URL manually and `--port 4317` only when a fixed loopback port is
-needed. Drag/drop or Browse Folder copies source into a Tapp-owned workspace. Connect GitHub lists
-repositories authorized to the local `gh` session and makes a shallow isolated clone.
-`tapp app /path/to/repo` intentionally works directly in that checkout.
-
-The local server binds to `127.0.0.1`. It owns workspace paths; browser requests cannot submit an
-arbitrary server path. Mutations require an `HttpOnly` same-site session cookie, the exact local
-Origin, and an in-memory CSRF token. Application runtimes, repository credentials, and evidence stay
-in the local process/filesystem. This is a local trust boundary, not hosted multi-tenancy.
-
-## Product journey
-
-1. **Connect** a copied folder, an explicit checkout, or a repository authorized by local `gh`.
-2. **Detect and choose** an iOS, Android, or web target. Continue automatically only when the target
-   and configuration are conclusive.
-3. **Build, launch, and explore** the real simulator, emulator/device, or browser surface.
-4. **Understand the UI Map** through observed states, transitions, controls, provenance, and gaps.
-5. **Review intent** by approving, rejecting, deferring, or constraining a compact release plan.
-6. **Generate drafts** of Tasks and contracts. Drafts remain visibly untrusted.
-7. **Validate** approved drafts deterministically against the real target.
-8. **Promote** only validated artifacts into the canonical suite and refreshed Application Model.
-9. **Gate** with autonomous evidence plus the promoted deterministic suite.
-10. **Baseline** only a passing, conclusive, target-scoped gate.
-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 `.tapp/flows/`; credential values are templated to
-environment references. Long-lived repository artifacts store binding names, not resolved secret
-values.
-
-## Verified reference journey
-
-`tests/browser-journey.test.js` drives the visible local browser against a fresh CommerceDemo copy.
-It exercises startup, a real live web surface and semantic action, UI Map creation, Flow recording
-and replay, proposal review, generation, deterministic validation, promotion, a first gate,
-baseline-aware rerun, and CI preview.
-
-The opt-in `tests/browser-native-journey.test.js` passed on 2026-08-06 against a booted iOS
-simulator: the browser built and installed a disposable DemoApp checkout, ran shared target
-preparation and exploration, rendered an observed UI Map, drove the live surface, and saved a
-repository-native iOS Flow. The equivalent Android browser journey was not verified in that audit
-because no emulator/device was connected.
-
-This evidence proves representative local journeys. It does not prove arbitrary frameworks,
-production credentials, third-party services, hosted execution, or complete inference of business
-intent.
-
-## Hosted relationship
-
-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.
-
-The old hosted preview and `cloud/` prototype do not satisfy this boundary. Follow
-[`SAAS-ARCHITECTURE.md`](SAAS-ARCHITECTURE.md) and do not market or accept private repositories until
-[`SAAS-READINESS.md`](SAAS-READINESS.md) passes.

package/docs/PRODUCT-ENGINE.md

@@ -1,103 +0,0 @@
-# One Tapp product engine
-
-Status: current product-engine contract as of 2026-08-08.
-
-Tapp has several interfaces, not several products. The source of truth for customer-critical
-operations is [`mcp-server/src/product-operations.js`](../mcp-server/src/product-operations.js).
-An interface may validate its transport and render a result; it must not redefine onboarding,
-review, trust, baseline, or gate semantics.
-
-## Product operation contract
-
-The shared engine owns these operations:
-
-| Operation | Authoritative result |
-|---|---|
-| `initializeProductProject` | detected targets, real exploration, Application Model, UI Map, release plan |
-| `readProductProject` | one current, read-only product snapshot for any interface |
-| `reviewProductPlan` | explicit approve/reject/defer decisions |
-| `generateProductPlan` | compile-checked but untrusted Task/contract drafts |
-| `validateProductPlan` | real-target, deterministic replay evidence |
-| `promoteProductPlan` | canonical Tasks/contracts, refreshed model/plan, updated map coverage |
-| `prepareProductCi` / `installProductCi` | target-aware workflow and machine-readable CI manifest |
-| `runProductGate` | autonomous evidence plus the committed deterministic suite and one gate decision |
-| `createProductBaseline` | conclusive, platform-and-target-specific comparison state |
-
-Deterministic contract execution is in
-[`mcp-server/src/product-execution.js`](../mcp-server/src/product-execution.js). It invokes platform
-executors directly; MCP does not shell through the CLI, and the browser does not shell through MCP.
-
-## Interfaces
-
-```text
-Browser Release Studio ─┐
-CLI                     ├── product-operations ── application model / UI Map / Tasks / contracts
-MCP                     ┘             │
-                                      └── deterministic executors / portable gate / evidence
-
-VS Code ── MCP client
-Desktop ── canonical artifact reader (migration to operation client remains)
-Action  ── portable gate adapter
-Hosted  ── tenant-aware SaaS adapter + queued isolated shared-operation workers (not built)
-```
-
-Current convergence:
-
-- the browser calls only shared product operations;
-- CLI initialization, plan lifecycle, deterministic draft validation, promotion, gate/baseline
-  lifecycle, and CI installation call the same operations. Native build preparation remains at the
-  adapter boundary and passes a resolved `.app` or APK into the shared gate;
-- MCP initialization, plan lifecycle, deterministic draft validation, promotion, baseline, and CI
-  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 `.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
-  isolation boundary. The new SaaS must call these shared operations only through the tenant-aware,
-  queued worker contract in [`SAAS-ARCHITECTURE.md`](SAAS-ARCHITECTURE.md).
-
-## Canonical repository protocol
-
-New product behavior writes only `.tapp/`:
-
-```text
-.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
-  release-plan.json         # proposals and explicit human decisions
-  tasks/                    # reusable deterministic semantic operations
-  contracts/                # reviewed business guarantees
-  baselines/<platform>/     # conclusive target-specific comparison state
-  ci.json                   # generated CI installation manifest
-```
-
-`.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
-
-1. Trust states (`pending`, `approved`, `validated-draft`, `promoted`) are computed by the engine.
-2. Interfaces render `readProductProject`; they do not infer readiness from file existence.
-3. Re-exploration refreshes evidence while preserving reviewed decisions everywhere.
-4. Promotion refreshes the Application Model immediately; no interface may show stale pre-promotion
-   requirements.
-5. Baselines are identified by platform and stable target id everywhere.
-6. An adapter-specific feature is not complete until its engine operation is useful without that
-   adapter.
-7. Equivalence tests should assert artifacts and structured results, not merely matching copy.
-
-## Remaining migration
-
-The next safe convergence work is deliberately narrow:
-
-1. replace desktop import/build orchestration with a local product-operation client;
-2. delete the two desktop detection/scaffolding paths only after equivalence fixtures pass;
-3. implement managed account, organization, and tenant authorization before connecting repositories;
-4. implement scoped GitHub authorization, private evidence, and disposable per-job
-   identity/simulator/credential isolation before accepting customer code;
-5. preserve CLI/MCP/VS Code/Action as adapters—do not rebuild their product logic.

package/docs/application-model.md

@@ -1,271 +0,0 @@
-# Application model and `tapp init`
-
-`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:
-
-- `.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
-the same keyless QA engine as `tapp qa` to build/install/launch or connect to one selected real
-target, merge the observed map, and construct the model and plan from that runtime evidence. It
-does not generate or approve tests, call AI, or claim contract validation. When iOS repository
-resolution actually builds and installs the detected Xcode container, the model records the exact
-scheme as runtime-observed validation and removes the corresponding confirmation blocker. Merely
-supplying a bundle id or prebuilt `.app` does not prove repository build configuration.
-
-## First inspection
-
-```bash
-# Read-only preview. For web, provide the owned runtime URL if already known.
-tapp init . --url http://127.0.0.1:3000 --dry-run \
-  --json-out /tmp/tapp-init-preview.json
-
-# Create canonical artifacts. Existing files are never overwritten implicitly.
-tapp init . --url http://127.0.0.1:3000
-
-# Build/start the detected web target, explore it, persist its UI Map, then stop it.
-tapp init . --explore --platform web --actions 40 --timeout 600
-
-# Or connect to an already-running owned environment.
-tapp init . --explore --platform web --url http://127.0.0.1:3000 \
-  --actions 40 --timeout 600
-
-# iOS can resolve a repository/Xcode container/.app/bundle id and build when needed.
-tapp init . --explore --platform ios --target .
-
-# Android can install an APK, then launch the explicit application id.
-tapp init . --explore --platform android \
-  --apk app/build/outputs/apk/debug/app-debug.apk --app-id com.acme.app
-
-# Re-inspect after source/UI Map changes while preserving explicit review decisions.
-tapp init . --url http://127.0.0.1:3000 --refresh
-
-# Re-explore after review without losing approve/reject/defer choices.
-tapp init . --refresh --explore --platform web --url http://127.0.0.1:3000
-```
-
-MCP clients use `tapp_init` with `operation: inspect|write|refresh|explore`. `inspect` is the safe
-default. `explore` writes real evidence, so the CLI rejects `--explore --dry-run`; the CLI also
-requires `--refresh --explore` once model/plan artifacts exist. Credentials are passed only to the
-runtime and are never written into the model, map, or plan.
-
-Successful repository-driven iOS build validation is portable and durable. The application model
-stores the repository-relative container, scheme, configuration, bundle id, and a
-`tapp-capture:<id>` evidence reference—never the local DerivedData or checkout path. A later
-source-only `tapp init --refresh` retains that validation when it still names the same detected
-container. Tapp does not infer equivalent proof from an installed application, an explicit bundle
-id, or a prebuilt artifact; those paths can demonstrate runtime reachability but cannot silently
-confirm the repository's Xcode scheme.
-
-## Actors and credential bindings
-
-Configure named actors once instead of repeating credentials or session policy across tests:
-
-```bash
-tapp actor set alice . --role member --session isolated --provisioning seeded \
-  --credential email=ALICE_EMAIL --credential password=ALICE_PASSWORD
-tapp actor set bob . --role member --session isolated --provisioning seeded \
-  --credential email=BOB_EMAIL --credential password=BOB_PASSWORD
-tapp actor list .
-tapp init . --refresh
-```
-
-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
-merges those reviewed placeholders with the central configuration, blocks missing/conflicting
-bindings, and never copies resolved values into the application model, release plan, UI Map, CI
-manifest, or generated workflow.
-
-When web `--url` is omitted, Tapp selects one detected browser target, runs only its internally
-derived lockfile-backed install command, runs its declared build script when present, and starts its
-`start`, `dev`, `serve`, or `preview` package script with argument-array process execution (never
-generated shell source). A static site with no script uses Tapp's local read-only static server. The
-runtime binds to an available loopback port, writes its log under the Tapp runtime directory, and is
-terminated after exploration even when QA fails. Multiple web targets, an unlocked dependency
-graph, an unrecognized start path, or backend-specific configuration produce explicit remediation;
-provide `--target` and/or an already-running owned `--url` in those cases. Running repository build
-scripts executes repository code and should only be used for a checkout the customer trusts.
-The managed loop never persists its ephemeral loopback URL as customer configuration. The model
-records `runtime.management: tapp-managed`, and the portable gate/Action reconstructs the same
-start/wait/stop lifecycle later. An explicitly supplied owned URL remains `customer-managed`.
-
-## What the model records
-
-Application Model v1 records:
-
-- detected iOS simulator, Android application, and browser targets;
-- inspectable build commands, project/module/container paths, scheme candidates, application ids,
-  owned URLs, missing confirmations, and exact runtime-observed target validation where Tapp itself
-  completed the repository build/install path;
-- actors, roles, provisioning modes, credential requirements/environment bindings, and
-  session-isolation boundaries without credential values;
-- business entities and capabilities explicitly declared by reviewed contracts or conservatively
-  derived from reusable Task names;
-- authored critical journeys, revenue paths, and cross-actor system invariants;
-- the shared UI Map's observed state/transition/control counts and uncovered ids;
-- the latest import exploration's verdict and explicit inconclusive status, when available;
-- existing Tasks and contracts;
-- blocking requirements and exact remediation.
-
-Every fact identifies its evidence class. The current deterministic importer uses:
-
-- `source-observed` for repository files and build metadata;
-- `runtime-observed` for a successful exact target build/install/exploration, with portable evidence;
-- `reviewed-artifact` for committed Tasks, contracts, and UI Map evidence;
-- `task-derived` or another source-derived status when a fact still requires review;
-- `authored-unvalidated` when a committed contract exists without current-revision replay proof.
-
-Runtime observation, source inference, optional AI proposals, and human decisions must not be
-collapsed into one confidence label. The artifact explicitly records that remote AI was not used.
-
-## Release-plan quality
-
-The deterministic planner starts with committed contracts, then proposes only evidence-grounded
-gaps:
-
-- a conservative cross-actor propagation guarantee when two explicitly configured isolated actors,
-  deterministic setup/teardown, compatible authentication/precondition screens, and an exact
-  content-producing Task output jointly prove that the proposal is grounded;
-- reusable Tasks not composed by a reviewed contract;
-- uncovered UI states carrying business signals such as authentication, pricing, checkout,
-  account, messaging, or settings behavior.
-
-Error pages, blank pages, loading surfaces, changelogs, and generic feature-description pages remain
-visible as UI Map coverage gaps but do not automatically become business contracts. The target is
-approximately 5–15 contracts for a sufficiently rich product, not an artificial quota for a small
-fixture. Every proposal includes business value, risk, criticality, actors, platforms, grounding,
-and the real-surface validation required before it can be trusted.
-
-## Explicit review
-
-```bash
-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 .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 .tapp/release-plan.json --project-dir . --platform web
-# Or connect to an already-running owned environment.
-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 .tapp/release-plan.json --project-dir . \
-  --item checkoutWorks
-```
-
-The MCP equivalent is `tapp_release_plan` with `read|review|generate|validate|promote`. Review
-changes decision metadata only. It cannot silently
-edit a Task, contract, selector, or assertion. On `tapp init --refresh`, decisions, constraints, and
-review notes are carried forward by stable item id; reviewed items no longer derived from current
-evidence are retained and marked stale instead of disappearing.
-
-A source-only refresh preserves recorded replay evidence. `tapp init --refresh --explore` carries
-the history forward but invalidates trust for affected generated Tasks and contracts: prior
-platform results move to historical evidence, status becomes `requires-revalidation`, and replay is
-required before the draft can be trusted against the newly observed revision. Exploration never
-silently self-heals or accepts the prior selector path.
-
-The macOS desktop Coverage experience reads these same files. Its **Application** tab explains
-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 `.tapp/ui-map.json` with current
-run evidence instead of building a separate desktop-only graph.
-
-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
-`.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
-action cannot be represented deterministically, or platform paths require incompatible semantic
-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 `.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
-platform passes. Failed replay remains visible and sets `trusted: false`; there is no selector
-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 `.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.
-
-## Baseline and CI handoff
-
-After promotion, complete the local onboarding loop with:
-
-```bash
-# Runs the ordinary autonomous QA + committed suites gate. Builds native targets when possible;
-# web targets can be detected, built, started, awaited, and stopped without a durable URL.
-tapp baseline create . --platform web
-
-# Or import an already-retained successful full-gate report after review.
-tapp baseline create . --platform web --from /path/to/tapp-report.json
-
-# Generate one target-aware job per model target plus a machine-readable manifest.
-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
-`.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
-environment are passed to autonomous exploration and deterministic Flow/contract replay; invalid
-JSON or unsupported value types fail before execution rather than silently testing different app
-configurations.
-
-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
-for deterministic multi-actor replay, and supports managed web startup, Android emulator
-provisioning, and the target-specific baseline. It does not commit,
-push, enable branch protection, or create remote resources. Use MCP `tapp_ci_setup` for the same
-read-only render, baseline import, and guarded install engine.
-
-## Current boundary
-
-Repository detection, one-target real exploration, first-map merge, evidence classification,
-runtime-observed iOS scheme confirmation, durable source-only refresh, deterministic planning, safe
-persistence, approve/reject/defer review, and compile-checked Task-backed draft generation are
-implemented. An empty map or a latest exploration marked inconclusive remains a blocking
-requirement; observing a login wall is not treated as useful coverage.
-
-`tapp init` does not yet orchestrate every detected target in one invocation, provision arbitrary
-web backends/services, automatically replay every approved draft, or promote validated drafts without
-explicit customer acceptance. Baseline creation and a reviewable per-target GitHub CI patch are now
-implemented as explicit post-promotion commands, but the generated workflow has not yet passed on
-current GitHub-hosted iOS, Android, and web runners. Task generation currently handles observed
-reachable navigation. Deterministic business planning is deliberately limited to cross-actor
-content propagation and one checkout-to-order-history persistence pattern supported by exact Task
-input/output, screen, actor, UI Map, and lifecycle evidence. General forms, broader payment shapes,
-dynamic value capture, messaging/reactions, role-asymmetric invariants, and incompatible platform
-journeys still require reviewed authoring. Optional
-AI business reasoning is also not wired into this path. Those missing stages remain completion
-blockers.

package/docs/scenarios.md

@@ -1,95 +0,0 @@
-# Multi-actor Scenarios
-
-A Scenario is Tapp's low-level deterministic multi-actor execution format in `.tapp/scenarios/*.yml`. It uses the same semantic actions, polling assertions, timeouts, evidence markers, and merge policy as a Flow, but adds isolated named actors, shared variables, and explicit lifecycle steps. The customer-facing business authoring layer is a TypeScript [release contract](release-contracts.md), which composes reusable Tasks and compiles to this runtime instead of duplicating UI steps.
-
-Ordinary replay is keyless. AI may propose a Scenario during authoring, but no model, API key, or coding agent participates when CI executes it.
-
-## Current support
-
-Web replay is implemented through one isolated Playwright browser context per actor. Cookies, local storage, and in-browser session state cannot leak between actors; all contexts point at the same deployed application and backend. The Action, portable gate, CLI, and MCP surface all consume the same file.
-
-iOS and Android still support sequential account switching inside ordinary Flows, but do not yet have first-class isolated multi-actor Scenario drivers. Tapp rejects those platform combinations instead of presenting sequential login/logout as equivalent proof.
-
-## Contract
-
-```yaml
-name: Alice publishes and Bob sees it
-kind: scenario
-platform: web
-url: http://127.0.0.1:4180
-timeoutMs: 6000
-vars:                         # shared deterministic data
-  POST: Scenario post 7319
-actors:
-  alice:
-    vars:                     # actor-scoped credentials/session inputs
-      EMAIL: alice@example.test
-      PASSWORD: demo
-  bob:
-    vars:
-      EMAIL: bob@example.test
-      PASSWORD: demo
-setup:
-  - request:                  # bounded, same-origin HTTP; never arbitrary shell
-      method: POST
-      path: /__tapp/reset
-      status: 200
-steps:
-  - actor: alice
-    type: { field: Email, value: $EMAIL }
-  - actor: alice
-    type: { field: Password, value: $PASSWORD }
-  - actor: alice
-    tap: Sign in
-  - actor: alice
-    type: { field: Post text, value: $POST }
-  - actor: alice
-    tap: Publish
-  - actor: bob
-    assert_exists: { target: $POST, timeoutMs: 6000 }
-teardown:
-  - request: { method: POST, path: /__tapp/reset, status: 200 }
-```
-
-- `actors` must contain at least two names. Every journey step names one of them.
-- Actor variables override shared variables. A committed value such as `$ALICE_PASSWORD` resolves only that explicitly referenced environment variable at run time; Tapp does not serialize the surrounding environment.
-- `setup` and `teardown` currently accept bounded HTTP request steps on the target origin. Teardown runs after a journey failure so state is still cleaned up.
-- Flow assertions poll until their bounded timeout. This models eventual consistency without blind sleeps or unbounded retries. A condition that never becomes true fails visibly.
-- Typed values are not written to step evidence. Results include actor, action, selector, status, and error; failures capture that actor's screen and final screenshots for all actors.
-- A failed Scenario always blocks the release gate, independently of whether autonomous single-user exploration found a problem.
-
-## Run it
-
-```bash
-tapp scenario validate .tapp/scenarios/social-system.yml
-ALICE_EMAIL=alice@example.test ALICE_PASSWORD=demo \
-BOB_EMAIL=bob@example.test BOB_PASSWORD=demo \
-  tapp scenario run .tapp/scenarios/social-system.yml
-
-tapp ci --platform web --url http://127.0.0.1:4180 \
-  --scenarios '.tapp/scenarios/*.yml' \
-  --json-out tapp-report.json --md-out tapp-report.md
-```
-
-GitHub Action:
-
-```yaml
-- uses: aarwitz/tapp@main
-  with:
-    platform: web
-    url: http://127.0.0.1:4180
-    scenarios: .tapp/scenarios/*.yml
-```
-
-MCP clients call `tapp_scenario_run` with `scenarioPath`, or an inline reviewed Scenario. The structured result identifies `kind: scenario`, actual executed/total steps, and actor-tagged steps.
-
-## Verified fixture and boundaries
-
-`SocialDemo/.tapp/contracts/social-system.contract.ts` is the reference system guarantee; the Scenario remains its low-level execution proof and backwards-compatible escape hatch. On 2026-08-04 the contract passed 41/41 compiled steps using two isolated contexts against one delayed shared backend. With `SOCIAL_DEMO_FAULT=hide-cross-actor-posts`, the unchanged contract failed for Bob at 19/41 and the portable merge gate exited non-zero specifically because one release contract failed.
-
-The fixture's `.tapp/project.json` is the central actor contract. It records Alice and Bob's
-roles, isolated sessions, seeded provisioning, reset lifecycle, and four environment-variable
-names. The release contract and Scenario consume those names; neither stores the public fixture
-values. Customer values belong in the local environment or CI secret store.
-
-This proves the contract and web implementation, not universal multi-user reliability. Real customers still need reset/provisioning hooks or dedicated test data, enough accessibility semantics to select controls, and a test backend whose eventual-consistency budget is known.