OpenAdaptAI · abrichr · Aug 20, 2026
@@ -73,6 +73,9 @@ jobs:
       # The curated Concepts and Ecosystem sections replace it. Re-enable only
       # if a maintained, product-accurate architecture page is reintroduced.
 
+      - name: Validate published version claims
+        run: uv run python scripts/check_published_version_claims.py --offline
+
       - name: Run tests against generated source
         run: uv run pytest tests/ -q
 

@@ -59,6 +59,19 @@ uv run mkdocs build --strict
 uv run python scripts/validate_docs.py
 ```
 
+The managed-runtime artifact tuple has one editable source:
+`docs/published-version-claims.json`. Change the claim's `version`, release
+commit, archive hashes, source-manifest evidence, and `verified_on` fields once,
+then render all marked pages:
+
+```bash
+uv run python scripts/render_published_version_claims.py
+uv run python scripts/render_published_version_claims.py --check
+```
+
+Do not edit the marked page values directly. The offline version-claim gate and
+the documentation deployment both fail when the committed render is stale.
+
 ## Tests
 
 ```bash

@@ -28,19 +28,36 @@ the highest-fidelity signal each surface offers.
 
 ### Web: Playwright
 
-A headless Chromium driven by Playwright drives the web substrate, and every
-example in these docs uses it. It exposes a full structured layer:
+Playwright drives the web substrate. Flow can launch Chromium or attach to one
+existing signed-in local Chromium tab through a loopback CDP endpoint. Both
+entry modes use the same recorder, compiler format, and governed runtime. The
+browser exposes a full structured layer:
 
 - **Structural rung**: reads the DOM element under a point, so resolution and
   [identity](identity-gate.md) can use stable selectors and structured text
   where they exist.
 - **Structural postconditions**: URL change, title change, new-tab opened.
 - **CI-friendly**: no OS permissions, no display server; the whole record →
   compile → replay loop runs in a container.
+- **Existing-session recording**: attach mode preserves a dedicated browser
+  profile that has already completed sign-in, SSO, or 2FA. Flow refuses remote
+  endpoints and ambiguous same-origin tabs. It does not navigate or close the
+  external browser. It records viewport and monitor-scale transitions as new
+  per-event coordinate baselines. An idle transition rebaselines and continues.
+  An action that overlaps an unverified transition aborts the recording and
+  publishes no complete metadata.
 
 It shares the same bundle, resolution ladder, and identity gate as every other
 substrate; nothing about the safety model is specific to it.
 
+The Chrome extension code in `openadapt-capture` does not define a second
+compiler or direct replay path. An extension acquisition path must use Flow's
+shared event and evidence schema, capture-time secret exclusion, authenticated
+session identity, acknowledged ordered delivery, and exact event/frame/viewport
+binding before Flow accepts its recording. Source-time secret exclusion, DOM
+identity, field geometry, and exact event/frame binding stay inside the
+compiler contract.
+
 ### Desktop: Windows (UIA)
 
 The public `WindowsBackend` now narrows the in-session boundary to typed

@@ -108,11 +108,11 @@ synthetic. A missing production dependency makes the affected operation
 unavailable rather than substituting a simulated success.
 
 The retained hosted-recorder qualification used a Flow 1.8.0 worker. The
-current Cloud managed-runtime manifest pins Flow 1.31.0 at release commit
-`2d225dea9a0ad29ca84ce1b037cc0ac671367e28`. Its wheel SHA-256 is
-`81133db1528ad1bb1f26e3fcb6aea61b0651db6d905cf2e4943e8383c1f3d29c` and
+current Cloud managed-runtime manifest pins Flow <!-- version-claim:hosted-runner-managed-runtime-pin:version -->1.31.0<!-- /version-claim:hosted-runner-managed-runtime-pin:version --> at release commit
+<code><!-- version-claim:hosted-runner-managed-runtime-pin:release_commit -->2d225dea9a0ad29ca84ce1b037cc0ac671367e28<!-- /version-claim:hosted-runner-managed-runtime-pin:release_commit --></code>. Its wheel SHA-256 is
+<code><!-- version-claim:hosted-runner-managed-runtime-pin:wheel_sha256 -->81133db1528ad1bb1f26e3fcb6aea61b0651db6d905cf2e4943e8383c1f3d29c<!-- /version-claim:hosted-runner-managed-runtime-pin:wheel_sha256 --></code> and
 its source SHA-256 is
-`cf1fc356d14d267df82be188de3e9a3575734f18f46ef91ac8075438cc731540`.
+<code><!-- version-claim:hosted-runner-managed-runtime-pin:sdist_sha256 -->cf1fc356d14d267df82be188de3e9a3575734f18f46ef91ac8075438cc731540<!-- /version-claim:hosted-runner-managed-runtime-pin:sdist_sha256 --></code>.
 The pin proves configured artifact identity. It does not prove that the build is
 deployed or that a hosted workflow passed acceptance. Public readiness checks
 live mode, authentication, database, private storage, runner, compiler,

@@ -6,8 +6,13 @@ description: >-
 
 # Connect the desktop app to a cloud workspace
 
-OpenAdapt Desktop is a **Beta supporting surface**. The local loop (record, compile, replay, teach) works offline and needs no
-account. A **cloud workspace** (`app.openadapt.ai`) adds an org-wide dashboard:
+OpenAdapt Desktop supplies the local record, compile, replay, and teach loop.
+It works offline and needs no account.
+
+**Desktop Production contract:**
+<span data-openadapt-production-target="desktop" aria-live="polite">Production requires an active signed admission for this exact release or deployment.</span>
+
+A **cloud workspace** (`app.openadapt.ai`) adds an org-wide dashboard:
 pushed workflows are visible and runs needing attention are triaged. This page
 covers the path: sign in → mint an ingest token → connect the desktop app → push
 a recording → see it in the dashboard.

@@ -22,11 +22,14 @@ you explicitly push it to a [cloud workspace](connect-to-cloud.md).
 
 Get the installer from
 [openadapt.ai/download](https://openadapt.ai/download). The page detects your OS
-and architecture and offers the right build. Public Beta release
-`desktop-v0.15.0` ships the complete Windows, macOS, and Linux installer set with
+and architecture and offers the right build. Release `desktop-v0.15.0` ships
+the complete Windows, macOS, and Linux installer set with
 `SHA256SUMS`, a CycloneDX SBOM, per-platform metadata, and build-provenance
 attestations.
 
+**Current Desktop release admission:**
+<span data-openadapt-production-target="desktop" aria-live="polite">Production requires an active signed admission for this exact release or deployment.</span>
+
 | OS | Installer |
 |---|---|
 | Windows | `.msi` or `.exe` |

@@ -1,67 +1,70 @@
-# Package and repository lifecycle
+# Product components and release admission
 
-OpenAdapt the product (the [demonstration compiler](../concepts/demonstration-compiler.md))
-is what most people need. Underneath it sits a set of open-source libraries and
-infrastructure the compiler and its research build on. This section is for
-contributors and integrators who use those pieces directly.
+OpenAdapt is one product. Install `openadapt` and use `openadapt flow …`. The
+public repositories below supply the product's launcher, compiler, recorder,
+desktop cockpit, agent bridge, and trust surfaces.
 
-!!! note "Product first"
-    If you want to compile and run a workflow, start with
-    [Get started](../get-started/index.md). The libraries below are the building
-    blocks behind OpenAdapt, not the way most users interact with it. Each links
-    to its source repository, where its own README is the source of truth.
+Each release has its own evidence state. The state cells below state the
+Production requirement. In the browser, a cell changes to **Production** only
+when the current canonical admission record contains a live, non-revoked
+admission for that exact release. The browser validates the live record against
+the hash in this documentation deployment. It does not use an older admission
+when the newest admission expires or is revoked. The site-wide product label
+also checks current PyPI metadata for
+`openadapt`, `openadapt-flow`, `openadapt-capture`, `openadapt-desktop`, and
+`openadapt-agent`. Each default version must equal its active admitted release,
+and that version must retain unyanked wheel and source artifacts.
 
-The end-user identity is deliberately singular: install `openadapt` and run
-`openadapt flow …`. The `openadapt-flow` repository is where contributors
-inspect and change the engine. See [Versions and compatibility](../reference/compatibility.md)
-for the tested package ranges.
+[Read the Production admission contract](../reference/production-lifecycle.md)
 
-## Lifecycle labels
+## Product components
 
-These labels describe the public role of a repository, not the quality of every
-module inside it:
+| Component | Current release admission | Public role |
+|---|---|---|
+| [OpenAdapt](https://github.com/OpenAdaptAI/OpenAdapt) | <span data-openadapt-production-target="openadapt" aria-live="polite">Production requires an active signed admission for this exact release or deployment.</span> | Installer, meta-package, and unified `openadapt flow` command. |
+| [OpenAdapt Flow](https://github.com/OpenAdaptAI/openadapt-flow) | <span data-openadapt-production-target="flow" aria-live="polite">Production requires an active signed admission for this exact release or deployment.</span> | Canonical demonstration compiler and governed runtime for Browser, native Windows, native macOS, native Linux, RDP, and Citrix/VDI. |
+| [OpenAdapt Cloud](https://app.openadapt.ai/) | <span data-openadapt-production-target="cloud" aria-live="polite">Production requires an active signed admission for this exact release or deployment.</span> | Managed control plane for organizations, exact-hash admission, browser runners, reports, billing, and usage. |
+| [OpenAdapt Desktop](https://github.com/OpenAdaptAI/openadapt-desktop) | <span data-openadapt-production-target="desktop" aria-live="polite">Production requires an active signed admission for this exact release or deployment.</span> | Windows, macOS, and Linux cockpit for recording, compilation, qualification, replay, and local review. |
+| [OpenAdapt Agent](https://github.com/OpenAdaptAI/openadapt-agent) | <span data-openadapt-production-target="agent" aria-live="polite">Production requires an active signed admission for this exact release or deployment.</span> | Governed bridge from MCP clients and Agent Skills to exact Flow bundles. |
+| [OpenAdapt Capture](https://github.com/OpenAdaptAI/openadapt-capture) | <span data-openadapt-production-target="capture" aria-live="polite">Production requires an active signed admission for this exact release or deployment.</span> | Canonical native recorder for screen, mouse, keyboard, timing, window scope, and media. Windows UIA evidence is emitted with the captured action. The shared observer protocol defines the macOS Accessibility and Linux AT-SPI integration boundary. RDP and Citrix remain pixel-observed at the remote boundary. |
+| OpenAdapt documentation | <span data-openadapt-production-target="docs" aria-live="polite">Production requires an active signed admission for this exact release or deployment.</span> | Version-bound product, operation, security, and qualification documentation at this site. |
 
-- **Beta**: an active product or component on the supported product path.
-- **Experimental**: an active integration whose contract is still being proven.
-- **Research**: evidence or model work, not required by deterministic replay.
-- **Deprecated**: retained for history or migration; no new integrations.
+Browser recording stays in Flow because DOM identity, field geometry,
+source-time secret masking, and Playwright execution use one browser session
+contract. Flow can launch Chromium or attach to one selected local tab. The
+Chrome extension code in the Capture repository does not define a second
+compiler or direct replay path. An extension acquisition path must satisfy the
+same authenticated event, evidence, masking, and frame-binding contract before
+Flow accepts its recording.
 
-## Product and optional components
+## Trust and interoperability libraries
 
-| Repository | Lifecycle | Public role |
-|---|---|---|
-| [OpenAdapt](https://github.com/OpenAdaptAI/OpenAdapt) | **Beta** | Installer/meta-package and unified `openadapt flow` dispatcher. |
-| [openadapt-flow](https://github.com/OpenAdaptAI/openadapt-flow) | **Beta** | Canonical compiler and governed runtime. Drives web, native Windows, native macOS, native Linux, RDP, and Citrix/VDI as first-class substrates behind one backend protocol. |
-| [OpenAdapt Cloud](https://app.openadapt.ai/) | **Beta** | Proprietary live control plane for the managed subscription: organizations, exact-hash admission, runner orchestration, reports, billing, and usage. |
-| [openadapt-desktop](https://github.com/OpenAdaptAI/openadapt-desktop) | **Beta** | Public `desktop-v0.15.0` provides Windows MSI/NSIS, macOS arm64/x64 DMG, and Linux AppImage/DEB installers. Every installer path is installed, launched, and uninstalled in the native release workflow; the release includes exact checksums, a CycloneDX SBOM, platform metadata, and build-provenance attestations. |
-| [openadapt-agent](https://github.com/OpenAdaptAI/openadapt-agent) | **Experimental** | Active v2 bridge that exposes governed Flow bundles to MCP clients and Agent Skills. The pre-v2 model-driven execution wrapper is the deprecated line; the repository itself is active. |
-| [openadapt-capture](https://github.com/OpenAdaptAI/openadapt-capture) | **Beta** | Canonical native screen, mouse, keyboard, timing, and window-scoped recorder behind Flow's Windows, macOS, Linux, RDP, and Citrix recording paths. Capture 1.1 retains Windows UIA evidence at action time; remote sessions remain externally black-box. Browser recording remains inside Flow's Playwright listener. |
-| [openadapt-privacy](https://github.com/OpenAdaptAI/openadapt-privacy) | **Experimental** | Optional PII/PHI scrubbing used on configured persist, log, and upload paths. |
-| [openadapt-types](https://github.com/OpenAdaptAI/openadapt-types) | **Experimental** | Shared interoperability schemas; contributor-facing, not an end-user product. |
+| Repository | Public role |
+|---|---|
+| [openadapt-privacy](https://github.com/OpenAdaptAI/openadapt-privacy) | Optional PII/PHI sanitization for configured persistence, logs, and artifact egress. |
+| [openadapt-types](https://github.com/OpenAdaptAI/openadapt-types) | Shared interoperability schemas for contributors and integrators. |
 
-## Research components
+## Evaluation and model development
 
-| Repository | Lifecycle | Public role |
-|---|---|---|
-| [openadapt-ml](https://github.com/OpenAdaptAI/openadapt-ml) | **Research** | VLM training, inference, and demonstration-conditioning work. Not required by the healthy compiler path. |
-| [openadapt-evals](https://github.com/OpenAdaptAI/openadapt-evals) | **Research** | GUI-agent and demonstration-conditioning evaluation infrastructure. |
-| [openadapt-grounding](https://github.com/OpenAdaptAI/openadapt-grounding) | **Research** | UI grounding experiments and model adapters. |
-| [openadapt-retrieval](https://github.com/OpenAdaptAI/openadapt-retrieval) | **Research** | Demonstration retrieval experiments. |
+| Repository | Public role |
+|---|---|
+| [openadapt-ml](https://github.com/OpenAdaptAI/openadapt-ml) | Optional VLM training, inference, and demonstration-conditioning work. The healthy compiler path does not require it. |
+| [openadapt-evals](https://github.com/OpenAdaptAI/openadapt-evals) | GUI workflow and demonstration-conditioning evaluation infrastructure. |
+| [openadapt-grounding](https://github.com/OpenAdaptAI/openadapt-grounding) | UI grounding mechanisms and model adapters. |
+| [openadapt-retrieval](https://github.com/OpenAdaptAI/openadapt-retrieval) | Demonstration retrieval mechanisms. |
 
 ## How the pieces fit
 
 ```mermaid
 flowchart LR
-    C[openadapt-capture<br/>optional recording] --> F[[openadapt-flow<br/>canonical compiler]]
+    C[openadapt-capture<br/>native recording] --> F[[openadapt-flow<br/>canonical compiler]]
+    B[Playwright browser<br/>recording] --> F
     F --> R[Deterministic<br/>replay bundle]
-    A[openadapt-agent<br/>MCP + Agent Skills bridge] --> F
-    ML[openadapt-ml<br/>grounding / identity models] -.optional on-prem appliance.-> F
-    E[openadapt-evals<br/>benchmarks] -.measures.-> F
+    A[openadapt-agent<br/>governed bridge] --> F
+    ML[optional models] -.resolve under drift.-> F
+    E[openadapt-evals] -.measures.-> F
 ```
 
-The compiler is the product. Capture feeds it native and remote demonstrations, the ML layer
-can supply optional on-prem models, Agent gives MCP clients and Agent Skills a
-governed route into Flow bundles, and evals measures adjacent research. This page
-intentionally does not expose internal developer tools as product components.
-See [Qualification evidence](../get-started/what-works-today.md) for integrated
-feature and backend coverage.
+See [Qualification evidence](../get-started/what-works-today.md) for bounded
+feature and backend results. Evidence for one task and environment does not
+extend to another workflow.
@@ -108,6 +108,12 @@ profiles require it explicitly.)
 Perform the task once. When you are done, press ++ctrl+c++ or close the browser
 window to finish. The recording is written to `rec/`.
 
+!!! tip "Keep an existing SSO or 2FA session"
+    Start a dedicated Chromium profile with a local remote-debugging port. Add
+    `--browser-cdp-endpoint http://127.0.0.1:9222` to attach the same recorder
+    to its one open same-origin tab. Flow does not navigate or close that
+    browser. See [Record your own app](../guides/record-your-app.md#use-an-existing-signed-in-chromium-session).
+
 !!! tip "Record a clean demonstration"
     Do the task the way you want it replayed: one clear path, no dead ends. The
     compiler treats your demonstration as evidence of intent, so a tidy run