npm - @aarwitz/tapp - Versions diffs - 0.15.0 - Mend

@aarwitz/tapp 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (77) hide show

package/AGENTS.md +123 -0
package/Harness/OCQAHarness/AppDelegate.swift +21 -0
package/Harness/OCQAHarness/Info.plist +26 -0
package/Harness/OCQAHarness.xcodeproj/project.pbxproj +199 -0
package/Harness/OCQAHarness.xcodeproj/xcshareddata/xcschemes/OCQAHarnessUITests.xcscheme +22 -0
package/Harness/OCQAHarnessUITests/ExplorerTests.swift +4526 -0
package/Harness/OCQAHarnessUITests/Info.plist +22 -0
package/Harness/generate-harness-xcodeproj.rb +254 -0
package/LICENSE +21 -0
package/README.md +374 -0
package/bin/tapp.js +1382 -0
package/browser/app.css +227 -0
package/browser/app.js +675 -0
package/browser/index.html +195 -0
package/browser/product-contract.js +25 -0
package/browser/view-model.js +16 -0
package/docs/BROWSER-PRODUCT.md +72 -0
package/docs/PRODUCT-ENGINE.md +102 -0
package/docs/application-model.md +276 -0
package/docs/scenarios.md +95 -0
package/mcp-server/src/android-driver.js +287 -0
package/mcp-server/src/android-explorer.js +197 -0
package/mcp-server/src/android-flow.js +89 -0
package/mcp-server/src/application-model.js +1597 -0
package/mcp-server/src/browser-product.js +659 -0
package/mcp-server/src/browser-workspaces.js +234 -0
package/mcp-server/src/ci-report.js +557 -0
package/mcp-server/src/ci-setup.js +359 -0
package/mcp-server/src/contract-authoring.js +10 -0
package/mcp-server/src/enrich.js +57 -0
package/mcp-server/src/flow-runtime.js +127 -0
package/mcp-server/src/html-report.js +124 -0
package/mcp-server/src/index.js +3775 -0
package/mcp-server/src/maintenance-proposal.js +178 -0
package/mcp-server/src/managed-operation.js +61 -0
package/mcp-server/src/pr-selection.js +841 -0
package/mcp-server/src/product-execution.js +155 -0
package/mcp-server/src/product-operations.js +526 -0
package/mcp-server/src/project-config.js +101 -0
package/mcp-server/src/release-contract.d.ts +81 -0
package/mcp-server/src/release-contract.js +226 -0
package/mcp-server/src/report.js +363 -0
package/mcp-server/src/scenario-runtime.js +139 -0
package/mcp-server/src/static-server.js +44 -0
package/mcp-server/src/task-runtime.js +266 -0
package/mcp-server/src/ui-map.js +661 -0
package/mcp-server/src/web-explorer.js +493 -0
package/mcp-server/src/web-flow.js +238 -0
package/package.json +82 -0
package/scripts/android-corpus-e2e.sh +30 -0
package/scripts/ci-gate.sh +323 -0
package/scripts/cleanup-xcode.sh +157 -0
package/scripts/compile-contract.js +27 -0
package/scripts/compile-flow.js +18 -0
package/scripts/corpus-apps.txt +9 -0
package/scripts/corpus-sweep.sh +121 -0
package/scripts/coverage-eval.sh +92 -0
package/scripts/coverage_eval_parse.py +95 -0
package/scripts/deploy-and-build.sh +99 -0
package/scripts/flow-platform.js +18 -0
package/scripts/flow_ai_judge.py +102 -0
package/scripts/flow_lib.py +154 -0
package/scripts/mutation-recall-desktop.sh +186 -0
package/scripts/mutation-recall.sh +121 -0
package/scripts/mutation_lib.py +128 -0
package/scripts/mutation_operators.py +144 -0
package/scripts/platform-gate.js +186 -0
package/scripts/pr-plan.js +68 -0
package/scripts/quick-capture.sh +419 -0
package/scripts/run-android-flow.js +27 -0
package/scripts/run-flow.sh +90 -0
package/scripts/run-web-flow.js +28 -0
package/scripts/run-web-scenario.js +23 -0
package/scripts/validation-matrix.sh +146 -0
package/scripts/vision-fp-eval.sh +206 -0
package/scripts/vision_escalation_responder.py +147 -0
package/scripts/vision_fp_probe.py +221 -0

package/browser/index.html ADDED Viewed

@@ -0,0 +1,195 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <meta name="description" content="Tapp turns repositories into UI maps, deterministic release contracts, and evidence-backed merge decisions across iOS, Android, and web.">
+  <meta name="tapp-api-base" content="">
+  <meta name="tapp-login-url" content="">
+  <title>Tapp</title>
+  <link rel="stylesheet" href="./assets/app.css">
+</head>
+<body>
+  <header class="topbar">
+    <button class="brand" id="brand-home" aria-label="Tapp overview"><span class="brand-mark">&#9757;&#65038;</span><span>tapp</span><small>release confidence</small></button>
+    <div class="top-actions">
+      <span class="mode-pill" id="mode-pill">Local engine</span>
+      <select id="repository-switcher" class="repository-switcher hidden" aria-label="Current repository"></select>
+      <button class="quiet hidden" id="refresh-project">Refresh</button>
+    </div>
+  </header>
+  <main class="source-onboarding hidden" id="source-onboarding">
+    <section class="welcome-copy">
+      <p class="eyebrow">RELEASE CONTRACTS FOR REAL APPLICATIONS</p>
+      <h1>Bring the product.<br>Tapp builds the proof.</h1>
+      <p>Connect a repository once. Tapp detects its targets, builds and explores the real application, maps what users can do, proposes the business journeys worth protecting, and installs deterministic release gates.</p>
+      <div class="platform-row" aria-label="Supported target platforms">
+        <span>iOS</span><span>Android</span><span>Web</span>
+      </div>
+    </section>
+    <section class="source-choices" aria-label="Connect a repository">
+      <article class="source-card local-runner-card">
+        <div class="source-icon">⌘</div>
+        <p class="eyebrow">THIS MAC</p>
+        <h2>Run from your checkout</h2>
+        <p>Your source never uploads. Tapp builds with local Xcode and drives your local simulator, while the web app shows progress and evidence.</p>
+        <div id="local-repositories"><small>Looking for connected Mac repositories…</small></div>
+      </article>
+      <article class="source-card drop-zone" id="repository-drop-zone" tabindex="0">
+        <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>
+        <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>
+      </article>
+      <article class="source-card github-card">
+        <div class="source-icon github-icon">⌘</div>
+        <p class="eyebrow">GITHUB</p>
+        <h2>Connect to GitHub</h2>
+        <p id="github-source-copy">Select one of the repositories authorized by your local GitHub session. Tapp clones an isolated checkout and never pushes silently.</p>
+        <button class="secondary" id="connect-github">Choose repository</button>
+        <small id="github-source-note">Local preview uses <code>gh auth</code>. Hosted Tapp will use repository-scoped GitHub App authorization.</small>
+      </article>
+    </section>
+    <div class="privacy-note"><strong id="privacy-note-title">Your code stays on this machine in local mode.</strong><span id="privacy-note-detail">Ordinary exploration, replay, and merge decisions are deterministic and require no API key.</span></div>
+  </main>
+  <div class="product-shell hidden" id="product-shell">
+    <aside class="sidebar">
+      <div class="project-identity">
+        <span class="project-avatar" id="project-avatar">A</span>
+        <div><strong id="sidebar-project-name">Product</strong><small id="sidebar-project-source">Repository</small></div>
+      </div>
+      <nav class="primary-nav" aria-label="Product navigation">
+        <button data-view="overview" class="active"><span>⌂</span>Overview</button>
+        <button data-view="runs"><span>▶</span>Runs <i id="run-count">0</i></button>
+        <button data-view="findings"><span>◇</span>Findings <i id="finding-count">0</i></button>
+        <button data-view="coverage"><span>⌘</span>Coverage</button>
+        <button data-view="contracts"><span>✓</span>Contracts <i id="contract-count">0</i></button>
+        <button data-view="settings"><span>⚙</span>Settings</button>
+      </nav>
+      <div class="sidebar-context">
+        <p class="eyebrow">SELECTED TARGET</p>
+        <strong id="sidebar-target">Select a target</strong>
+        <small id="sidebar-runner">Runner not checked</small>
+      </div>
+      <button class="sidebar-source" id="change-source">＋ Add another repository</button>
+      <div class="keyless-note"><span>●</span><div><strong>Keyless replay</strong><small>AI is outside the ordinary gate loop.</small></div></div>
+    </aside>
+    <main class="workspace">
+      <section class="workspace-view active" data-view-panel="overview" id="overview">
+        <div class="view-heading">
+          <div><p class="eyebrow">OVERVIEW</p><h1 id="app-name">Your release workspace</h1><p id="app-summary">Inspect the repository to discover product targets and release intent.</p></div>
+          <div class="decision-card neutral" id="decision-card"><span class="decision-label">CURRENT DECISION</span><strong id="decision-title">Not evaluated</strong><span id="decision-detail">Run a conclusive release gate to establish evidence.</span></div>
+        </div>
+        <nav class="journey" aria-label="Release setup progress">
+          <button data-jump="connect"><span>1</span><b>Connect</b><small>Repository</small></button>
+          <button data-jump="target-stage"><span>2</span><b>Target</b><small>Build & runtime</small></button>
+          <button data-jump="map"><span>3</span><b>Map</b><small>Observed product</small></button>
+          <button data-jump="contracts"><span>4</span><b>Contracts</b><small>Review intent</small></button>
+          <button data-jump="validate"><span>5</span><b>Validate</b><small>Keyless replay</small></button>
+          <button data-jump="evidence"><span>6</span><b>Gate</b><small>Decision & CI</small></button>
+        </nav>
+        <section class="panel section" id="connect">
+          <div class="section-heading"><div><p class="eyebrow">CONNECTED REPOSITORY</p><h2 id="repository-title">Repository</h2><p id="repository-detail">Tapp reads canonical repository artifacts and writes only explicit, reviewable changes.</p></div><span class="status-chip" id="connect-status">Not inspected</span></div>
+          <div class="button-row"><button class="secondary" id="inspect">Inspect repository</button><button class="quiet" data-view="settings">Repository settings</button></div>
+        </section>
+        <section class="panel section" id="target-stage">
+          <div class="section-heading"><div><p class="eyebrow">BUILD & RUN</p><h2>Choose the product target</h2><p>Tapp detected these targets from source. Multiple targets require an explicit choice; build results validate—not replace—the model.</p></div><span class="status-chip" id="target-status">No target selected</span></div>
+          <div class="target-choice-callout hidden" id="target-choice-callout"><span>1</span><div><strong>Choose what Tapp should test</strong><small>Nothing will build until you select a target. Tapp never guesses when a repository contains multiple applications.</small></div></div>
+          <div id="targets" class="target-grid"><div class="empty">Inspect the repository to detect iOS, Android, and web targets.</div></div>
+          <div class="runtime-row hidden" id="runtime-row">
+            <label class="field android-runtime hidden" id="serial-field"><span>Android device serial <i>optional</i></span><input id="android-serial" placeholder="emulator-5554"><small>Leave blank to use the first connected and authorized device.</small></label>
+            <div class="run-cta"><div class="button-row"><button class="primary" id="explore">Build, launch & explore</button><button class="secondary" id="start-session">Open live app</button></div><small id="explore-help">Select one target to continue.</small></div>
+          </div>
+          <div id="requirements"></div>
+        </section>
+        <section class="panel section live-session-panel hidden" id="live-session-panel">
+          <div class="section-heading"><div><p class="eyebrow">LIVE APPLICATION</p><h2 id="live-screen-title">Running target</h2><p>See and drive the same real application surface used by Tapp's deterministic engine. Semantic controls refresh after every action.</p></div><div class="button-row"><button class="quiet" id="refresh-live-session">Refresh</button><button class="secondary" id="end-session">End session</button></div></div>
+          <div class="live-layout">
+            <div class="live-frame-shell"><div class="live-frame-head"><span id="live-platform">Target</span><span id="live-recorded-steps">0 recorded steps</span></div><div class="live-frame"><img id="live-frame-image" alt="Current application screen"><div id="live-frame-loading">Capturing live application…</div></div><div class="flow-recorder"><div><strong>Keep this journey as a deterministic Flow</strong><small>Successful actions are recorded with semantic selectors. Existing files are preserved.</small></div><label><span>Flow name</span><input id="live-flow-name" placeholder="Checkout smoke"></label><button class="primary" id="save-live-flow">Save Flow</button></div></div>
+            <aside class="live-controls"><div class="live-controls-heading"><div><strong>Semantic controls</strong><small id="live-control-count">0 available</small></div></div><div id="live-control-list"><div class="empty">Controls appear when the session starts.</div></div><div class="manual-action"><label><span>Target or field</span><input id="live-action-target" placeholder="Accessibility id or visible label"></label><label><span>Text <i>for type/wait</i></span><input id="live-action-text" autocomplete="off"></label><div class="button-row"><button class="secondary" id="live-tap">Tap</button><button class="secondary" id="live-type">Type</button><button class="quiet" id="live-back">Back</button><button class="quiet" id="live-swipe">Swipe up</button></div></div></aside>
+          </div>
+        </section>
+        <section class="overview-grid">
+          <article class="panel summary-panel"><div class="section-heading compact"><div><p class="eyebrow">LATEST EVIDENCE</p><h2>What changed?</h2></div><button class="quiet" data-view="runs">All runs</button></div><div id="overview-evidence"><div class="empty">No release run yet.</div></div></article>
+          <article class="panel summary-panel"><div class="section-heading compact"><div><p class="eyebrow">COVERAGE</p><h2>Observed surface</h2></div><button class="quiet" data-view="coverage">Open map</button></div><div id="overview-coverage" class="metric-grid"></div></article>
+        </section>
+      </section>
+      <section class="workspace-view" data-view-panel="runs">
+        <div class="view-heading simple"><div><p class="eyebrow">RUNS</p><h1>Release history</h1><p>Every autonomous sweep, deterministic replay, finding, and decision stays inspectable.</p></div><button class="primary" id="run-gate">Run release gate</button></div>
+        <div class="split-view">
+          <section class="panel list-panel" id="runs-list"><div class="empty">No runs yet.</div></section>
+          <section class="panel detail-panel" id="run-detail"><div class="empty">Select a run to inspect its decision, checks, findings, and artifacts.</div></section>
+        </div>
+      </section>
+      <section class="workspace-view" data-view-panel="findings">
+        <div class="view-heading simple"><div><p class="eyebrow">FINDINGS</p><h1>What needs attention</h1><p>Findings preserve their severity and regression state. A failed contract is never silently healed.</p></div><select id="finding-filter"><option value="all">All severities</option><option value="critical">Critical</option><option value="high">High</option><option value="medium">Medium</option><option value="low">Low</option></select></div>
+        <div class="split-view findings-layout"><section class="panel list-panel" id="findings-list"><div class="empty">No findings yet.</div></section><section class="panel detail-panel" id="finding-detail"><div class="empty">Select a finding to inspect its evidence.</div></section></div>
+      </section>
+      <section class="workspace-view" data-view-panel="coverage" id="map">
+        <div class="view-heading simple"><div><p class="eyebrow">COVERAGE</p><h1>The product Tapp understands</h1><p>One platform-neutral Application Model and UI Map power exploration, planning, maintenance, CLI, MCP, and CI.</p></div><span class="metric" id="map-metric">0 states</span></div>
+        <div class="subnav"><button data-coverage-tab="map" class="active">Flow Map</button><button data-coverage-tab="screens">Screens</button><button data-coverage-tab="application">Application</button><button data-coverage-tab="plan">Release Plan</button></div>
+        <section class="coverage-panel active" data-coverage-panel="map"><div class="map-layout"><div class="map-canvas" id="map-canvas"><div class="empty">Explore the real product to build its map.</div></div><aside id="coverage-summary" class="coverage-summary"></aside></div><div id="transition-list" class="transition-list"></div></section>
+        <section class="coverage-panel" data-coverage-panel="screens"><div class="panel table-panel" id="screen-list"><div class="empty">No observed screens yet.</div></div></section>
+        <section class="coverage-panel" data-coverage-panel="application"><div class="application-grid" id="application-model"><div class="empty">Inspect the repository to build its Application Model.</div></div></section>
+        <section class="coverage-panel" data-coverage-panel="plan"><div id="coverage-plan-list" class="plan-list"><div class="empty">No release plan yet.</div></div></section>
+      </section>
+      <section class="workspace-view" data-view-panel="contracts" id="contracts">
+        <div class="view-heading simple"><div><p class="eyebrow">RELEASE CONTRACTS</p><h1>Review business guarantees</h1><p>Approve a compact set of important outcomes. Tapp composes reusable Tasks instead of generating one script for every situation.</p></div><span class="status-chip" id="plan-status">No plan</span></div>
+        <section class="panel section">
+          <div class="plan-toolbar"><button class="quiet" id="approve-high">Approve high & critical</button><button class="quiet" id="defer-rest">Defer undecided</button><span class="spacer"></span><button class="primary" id="save-review">Save review</button></div>
+          <div id="plan-list" class="plan-list"><div class="empty">Inspect and explore to create a grounded release plan.</div></div>
+        </section>
+        <section class="panel section" id="validate">
+          <div class="section-heading"><div><p class="eyebrow">DETERMINISTIC SUITE</p><h2>Generate, replay, then promote</h2><p>Draft Tasks and contracts remain untrusted until they pass without AI against the selected real target. Promotion is explicit.</p></div><span class="status-chip" id="validation-status">Not generated</span></div>
+          <div class="pipeline"><article><span>01</span><h3>Generate drafts</h3><p>Compose reusable Tasks and TypeScript contracts from approved, grounded intent.</p><button class="secondary" id="generate">Generate</button></article><article><span>02</span><h3>Replay without AI</h3><p>Execute exact assertions and bounded waits on the actual selected platform.</p><button class="secondary" id="validate-drafts">Validate</button></article><article><span>03</span><h3>Promote reviewed proof</h3><p>Move only validated drafts into the committed suite and update map coverage.</p><button class="secondary" id="promote">Promote</button></article></div>
+          <div id="artifact-list" class="artifact-list"></div>
+        </section>
+      </section>
+      <section class="workspace-view" data-view-panel="settings">
+        <div class="view-heading simple"><div><p class="eyebrow">SETTINGS</p><h1>Project and execution</h1><p>Only unavoidable target, environment, actor, and credential inputs belong here.</p></div></div>
+        <div class="settings-grid">
+          <section class="panel settings-section"><p class="eyebrow">REPOSITORY</p><h2>Source</h2><div id="settings-repository"></div><button class="secondary" id="settings-add-repository">Add repository</button></section>
+          <section class="panel settings-section"><p class="eyebrow">RUNNERS</p><h2>Execution surfaces</h2><div id="runner-list"></div></section>
+          <section class="panel settings-section"><p class="eyebrow">ACTORS & CREDENTIALS</p><h2>Runtime-only values</h2><p>Values stay in this browser session and process environment; they are never written into repository artifacts or job results.</p><label class="field"><span>Test email</span><input id="test-email" autocomplete="off"></label><label class="field"><span>Test password</span><input id="test-password" type="password" autocomplete="new-password"></label><div id="actor-list" class="actor-list"></div></section>
+          <section class="panel settings-section"><p class="eyebrow">AI & DATA</p><h2>Optional orchestration</h2><div class="setting-row"><div><strong>Remote AI</strong><small>Planning and maintenance only. Deterministic execution does not need it.</small></div><span class="status-chip">Off</span></div><p class="honesty">Remote AI consent and provider controls are not yet exposed in this local browser build. Tapp will not opt you in implicitly.</p></section>
+        </div>
+        <section class="panel section" id="evidence">
+          <div class="section-heading"><div><p class="eyebrow">RELEASE EVIDENCE & CI</p><h2>Install the same decision in GitHub</h2><p>Preview the target-aware workflow, required secrets, unresolved configuration, and exact policy before writing anything.</p></div><div class="button-row"><button class="secondary" id="create-baseline" disabled>Establish baseline</button><button class="secondary" id="preview-ci">Preview CI</button><button class="primary" id="install-ci">Write reviewable patch</button></div></div>
+          <div id="latest-evidence" class="evidence-grid"><div class="empty">No release run yet.</div></div>
+          <pre id="ci-preview" class="code-preview hidden"></pre>
+        </section>
+      </section>
+    </main>
+  </div>
+  <dialog id="github-dialog">
+    <form method="dialog" class="dialog-shell">
+      <div class="dialog-heading"><div><p class="eyebrow">CONNECT TO GITHUB</p><h2>Select a repository</h2><p>Tapp only displays repositories available to your authenticated local GitHub session.</p></div><button class="quiet" value="cancel" aria-label="Close">Close</button></div>
+      <input class="search-input" id="github-search" placeholder="Search repositories…" autocomplete="off">
+      <div id="github-repositories" class="github-repositories"><div class="empty">Loading authorized repositories…</div></div>
+    </form>
+  </dialog>
+  <div class="operation-drawer hidden" id="operation-drawer" role="status" aria-live="polite"><div class="spinner"></div><div class="operation-copy"><strong id="operation-title">Working…</strong><p id="operation-progress">Starting operation</p><div class="progress-track"><span id="operation-progress-bar"></span></div></div></div>
+  <div class="toast hidden" id="toast"></div>
+  <script type="module" src="./assets/app.js"></script>
+</body>
+</html>

package/browser/product-contract.js ADDED Viewed

@@ -0,0 +1,25 @@
+// Executable parity contract for Tapp's one customer-facing browser product.
+// Both the local adapter and hosted adapter must serve this same application.
+export const customerProductContract = Object.freeze({
+  schemaVersion: 1,
+  product: "Tapp",
+  interface: "customer-browser",
+  targetPlatforms: ["ios", "android", "web"],
+  repositorySources: ["local-folder", "github"],
+  views: [
+    { id: "overview", label: "Overview", capabilities: ["release-decision", "onboarding-progress", "current-operation", "latest-evidence"] },
+    { id: "runs", label: "Runs", capabilities: ["run-history", "run-detail", "timeline", "screenshots", "recordings", "logs", "artifacts"] },
+    { id: "findings", label: "Findings", capabilities: ["finding-list", "severity-filter", "regression-state", "evidence"] },
+    { id: "coverage", label: "Coverage", capabilities: ["application-model", "ui-map", "screens", "transitions", "controls", "task-coverage", "contract-coverage"] },
+    { id: "contracts", label: "Contracts", capabilities: ["release-plan-review", "task-generation", "contract-generation", "deterministic-validation", "explicit-promotion"] },
+    { id: "settings", label: "Settings", capabilities: ["target-selection", "runner-status", "runtime-inputs", "actors", "credentials", "ai-consent", "ci-installation"] },
+  ],
+  operations: ["initialize", "session-start", "session-act", "session-save-flow", "session-end", "review", "generate", "validate", "promote", "gate", "baseline", "ci-preview", "ci-install"],
+  invariants: [
+    "Browser is the Tapp customer interface; web is one target platform.",
+    "Repository paths are selected by the server or imported into isolated workspaces.",
+    "AI is optional for planning; deterministic replay and ordinary merge decisions are keyless.",
+    "Generated Tasks and contracts remain untrusted until real replay passes and promotion is explicit.",
+    "The internal fleet console is not a customer product surface.",
+  ],
+});

package/browser/view-model.js ADDED Viewed

@@ -0,0 +1,16 @@
+export function productJourneyFlags({ status = {}, hasTarget = false, hasEvidence = false } = {}) {
+  return [
+    true,
+    hasTarget,
+    status.explored === true,
+    status.reviewComplete === true,
+    // A committed or promoted contract is not proof that it replayed on the
+    // current revision. Only current validation evidence completes this step.
+    status.validated === true,
+    hasEvidence,
+  ];
+}
+export function operationIsPending(status) {
+  return ["queued", "claimed", "running"].includes(String(status || ""));
+}

package/docs/BROWSER-PRODUCT.md ADDED Viewed

@@ -0,0 +1,72 @@
+# 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 `.autotap/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
+`app.runtapp.com` 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 ADDED Viewed

@@ -0,0 +1,102 @@
+# 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 `.autotap` 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 `.autotap/`:
+```text
+.autotap/
+  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
+```
+`.autotap.yml` and `.tapp.yml` are legacy compatibility inputs, not parallel sources of product
+truth. Do not add a fourth configuration format. Migration readers may normalize old input into the
+canonical model; only an explicit reviewed operation may write new repository artifacts.
+## 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.