@aarwitz/tapp 0.16.5 → 0.17.0-rc.10

package/docs/BROWSER-PRODUCT.md

@@ -0,0 +1,75 @@
+# Browser Release Studio
+
+Status: current local-product contract as of 2026-08-08.
+
+The browser Release Studio is an **optional local workspace**, not the current launch surface — the
+**npm package (CLI + MCP + the GitHub Action) is the current objective** (ADR-0005). The Studio, the
+VS Code extension, the desktop app, and the future managed SaaS are separate/paused tracks. 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 all 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. The managed SaaS is a
+separate, paused track (see the private source repository); do not market or accept private
+repositories until its readiness gate passes.

package/docs/PRODUCT-ENGINE.md

@@ -0,0 +1,107 @@
+# 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 a tenant-aware,
+  queued worker contract (defined in the private source repository's SaaS architecture doc).
+
+## 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, and `.tapp/` holds repository artifacts. These are
+the only names the runtime reads; the pre-rename `.autotap.yml`, `.autotap/`, and `AUTOTAP_*` inputs
+are no longer supported. Do not add another configuration format, and do not reintroduce a legacy
+reader. Only an explicit reviewed operation may write new repository artifacts.
+
+## Anti-duplication rules
+
+0. Exploration (`explore`, formerly `qa`) observes and surfaces findings + evidence + UI Map; it must
+   not render a release outcome. Only the gate (`runProductGate`) applies versioned deterministic
+   policy to findings + coverage + selected suites + an optional baseline and computes
+   `pass | fail | inconclusive` (ADR-0005, in the private source repository).
+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

@@ -0,0 +1,278 @@
+# 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 explore` 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.
+
+A fresh repository with more than one detected application target is never resolved by detection
+order. Bare `tapp init . --explore` prompts in a human TTY; non-interactive CLI/MCP callers receive
+exact `--platform`/`--target` commands before any build or write, and MCP also carries them as
+structured `target-selection-required` choices. The selected run records that target as the default
+for later bare exploration, but the application model retains the repository's other detected targets
+and their unmet coverage.
+
+## 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
+refreshes existing model/plan artifacts through the same decision-preserving semantics. 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 finding count 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 exploration + 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

@@ -0,0 +1,95 @@
+# 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**, 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.