From d5da1d9e9580c5f6ddffbeb37b6466500b47543b Mon Sep 17 00:00:00 2001 From: abrichr Date: Sat, 1 Aug 2026 11:11:49 +0200 Subject: [PATCH] docs: align releases and simplify first run --- docs/commercial/index.md | 2 +- docs/commercial/oem-brief.md | 6 +++--- docs/desktop/install.md | 6 +++--- docs/ecosystem/index.md | 2 +- docs/get-started/index.md | 19 ++++++++++++++++--- docs/get-started/what-works-today.md | 2 +- docs/guides/security-and-data-handling.md | 4 ++-- docs/guides/security-review.md | 2 +- docs/reference/compatibility.md | 9 ++++++--- mkdocs.yml | 2 +- 10 files changed, 35 insertions(+), 19 deletions(-) diff --git a/docs/commercial/index.md b/docs/commercial/index.md index fa1f14a..8346a85 100644 --- a/docs/commercial/index.md +++ b/docs/commercial/index.md @@ -31,7 +31,7 @@ automate; a well-evidenced "do not automate" is a full-value deliverable. | [Security packet](security-packet.md) | Answering a security or IT review. | | [Deployment boundaries](deployment-boundaries.md) | Explaining where execution and sensitive data live. | | [External Citrix zero-install brief](citrix-external-brief.md) | A buyer whose workflow lives behind Citrix or VDI. | -| [OpenAdapt Execute private-pilot guide](oem-brief.md) | A vendor that wants to embed verified execution. The public API is not available yet. | +| [OpenAdapt Execute private-pilot guide](oem-brief.md) | A vendor that wants to embed verified execution. The API is available to approved private-pilot partners with scoped credentials. | | [Procurement FAQ](procurement-faq.md) | Procurement, legal, and vendor-risk questions. | ## Honesty rules for this section diff --git a/docs/commercial/oem-brief.md b/docs/commercial/oem-brief.md index 35cb06c..79751bf 100644 --- a/docs/commercial/oem-brief.md +++ b/docs/commercial/oem-brief.md @@ -23,7 +23,7 @@ the customer system. !!! note "Private pilot. Not a public API." This page describes the private-pilot product contract. It is not an self-service integration recipe and it does not publish partner access, - credentials, an SDK, or a webhook URL. `openadapt-types` 0.8.0 publishes + credentials, an SDK, or a webhook URL. `openadapt-types` 0.9.0 publishes the shared async Execute schema, OpenAPI document, and signed decision contract. OpenAdapt Cloud provides private execution, customer-runner coordination, and receipt delivery for approved pilot partners. @@ -146,7 +146,7 @@ binds the decision, the runner transition, and the final state to the exact task and authorization. The released public contract for this round trip is -`openadapt-types` 0.8.0. It defines the async Execute schema and OpenAPI +`openadapt-types` 0.9.0. It defines the async Execute schema and OpenAPI document, plus signed, PHI-safe decision tasks and receipts. Flow and Cloud use this contract for the decision relay and private-pilot execution. The partner event stream does not contain raw screenshots or live record data. @@ -208,7 +208,7 @@ commercial compatibility pack. | Layer | Availability | Role | |---|---|---| | OpenAdapt Flow | MIT-licensed | Local compiler, governed runtime, transaction outcomes, qualification tools, and receipt mechanisms. | -| `openadapt-types` 0.8.0 | MIT-licensed and released | Shared async Execute schema and OpenAPI document, plus signed decision-task and decision-receipt contracts. | +| `openadapt-types` 0.9.0 | MIT-licensed and released | Shared async Execute schema and OpenAPI document, plus signed decision-task and decision-receipt contracts. | | OpenAdapt Cloud foundation | Private and deployed | Tenant control plane, private Execute endpoints, customer-runner coordination, signed decision relay, audit records, and managed operations. | | OpenAdapt Execute | Private pilot | Versioned transaction submission, status, receipt delivery, and partner integration for approved pilot partners. | | Compatibility packs and verifier recipes | Commercial | Per-application and per-environment qualification assets, deployment evidence, and support. | diff --git a/docs/desktop/install.md b/docs/desktop/install.md index ffb3231..74d4599 100644 --- a/docs/desktop/install.md +++ b/docs/desktop/install.md @@ -23,7 +23,7 @@ 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.14.0` ships the complete Windows, macOS, and Linux installer set with +`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. @@ -111,7 +111,7 @@ first-week failures. ## During a governed run -Desktop 0.14.0 can show a separate always-on-top status surface without adding +Desktop 0.15.0 can show a separate always-on-top status surface without adding anything to the target application. While OpenAdapt is observing or executing, the surface is non-focusable, ignores pointer input, exposes no controls, and is excluded from capture before it becomes visible. Controls become interactive @@ -127,7 +127,7 @@ and disappears if neither corner is safe. These presentation elements are not verification evidence and do not weaken the pointer, focus, or capture-exclusion boundary. [Watch the public demo](https://app.openadapt.ai/demo#footage) or review the exact released -[control-overlay contract](https://github.com/OpenAdaptAI/openadapt-desktop/blob/desktop-v0.14.0/docs/CONTROL_OVERLAY.md). +[control-overlay contract](https://github.com/OpenAdaptAI/openadapt-desktop/blob/desktop-v0.15.0/docs/CONTROL_OVERLAY.md). ## Where to go next diff --git a/docs/ecosystem/index.md b/docs/ecosystem/index.md index 32cd0a5..663bf14 100644 --- a/docs/ecosystem/index.md +++ b/docs/ecosystem/index.md @@ -33,7 +33,7 @@ module inside it: | [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.14.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-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. | diff --git a/docs/get-started/index.md b/docs/get-started/index.md index 01c2dc9..8bc87e3 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -6,9 +6,13 @@ description: >- # Get started -OpenAdapt turns a single demonstration into a deterministic, locally-run -workflow. The fastest path takes two commands and needs no account, target -application, API key, or operating-system automation permission: +Start with one complete local result. Then choose the guide for your target +surface. You do not need to understand the package layout first. + +## First success: two commands + +The fastest path needs no account, target application, API key, or +operating-system automation permission: ```bash python -m pip install --upgrade 'openadapt[browser]' @@ -40,6 +44,15 @@ openadapt flow visualize openadapt-quickstart/bundle --out graph.html openadapt flow lint openadapt-quickstart/bundle ``` +You can stop here after your first run. Next, use one of these paths: + +| Goal | Next guide | +|---|---| +| Record one real browser workflow | [Your first workflow](first-workflow.md) | +| Use the Desktop application | [Install Desktop](../desktop/install.md) | +| Use native desktop, RDP, or Citrix | [Install a different execution surface](#install-a-different-execution-surface) | +| Prepare a qualified production run | [Move from demo to deployment](#move-from-demo-to-deployment) | + !!! important "A tutorial result is not production certification" The bundled fixture proves that the local product path and its Standard verification gates work. It certifies only this bundled synthetic task, diff --git a/docs/get-started/what-works-today.md b/docs/get-started/what-works-today.md index ca2e56a..1951291 100644 --- a/docs/get-started/what-works-today.md +++ b/docs/get-started/what-works-today.md @@ -68,7 +68,7 @@ customer-controlled runtime connected to the same governance model. | Native Linux backend | **Supported** | Required current-main job [`linux-atspi-x11`](https://github.com/OpenAdaptAI/openadapt-flow/actions/runs/30059807758/job/89378981573) at exact Flow commit `3de5fc67acf3024a621f812c5a6ed9be07fac335` ran one fresh GTK3 process per trial on Ubuntu 24.04 X11/AT-SPI. It confirmed 3/3 exact-file effects, 3/3 ambiguous-target refusals, and 3/3 stale-target refusals, with 0 silent incorrect successes, 0 over-halts, 0 operator interventions, and 0 model calls. | Native receipts prove AT-SPI delivery only; independent exact file bytes or confirmed absence prove effects. This is bounded to the in-tree GTK3 fixture and CI Xvfb image; it does not establish Wayland or arbitrary third-party application support. | | RDP backend | **Supported** | Two bounded results exercise complementary RDP paths. Aardwolf 0.2.14 over a Parallels Windows 11 VM completed 3/3 Windows Run-dialog file effects with independent guest-tools readback. The accepted full governed lifecycle at mechanism commit `6031fde` recorded, compiled, and replayed a synthetic note workflow through real FreeRDP3-transported pixels/input: 3/3 healthy effects and 3/3 drift safe-halts, with zero model calls, silent incorrect successes, false completions, drift writes, or healthy over-halts. Consequential remote actions now acquire a fresh frame, re-resolve target and identity, and use a one-shot input lease that refuses changed session context, pixels, dimensions, or readiness before delivery. Review the [Aardwolf/Windows report](https://github.com/OpenAdaptAI/openadapt-flow/blob/6610d24cebba27918b8ea507b2f05a094057ac85/benchmark/rdp/results_82a658a_20260718.sanitized.json), the [FreeRDP lifecycle report](https://github.com/OpenAdaptAI/openadapt-flow/blob/affedc5f1f0de533a0744deaa8e30a203c91c6b3/benchmark/rdp_ladder/results.json), [Flow PR #142](https://github.com/OpenAdaptAI/openadapt-flow/pull/142), [Flow PR #177](https://github.com/OpenAdaptAI/openadapt-flow/pull/177), and [Flow PR #238](https://github.com/OpenAdaptAI/openadapt-flow/pull/238). | The Windows batch qualifies its exact task, snapshot, transport, and oracle. The FreeRDP batch qualifies a synthetic Linux Tk task over a real RDP round trip; it is not Aardwolf, a Windows-app qualification, Citrix ICA/HDX, or WAN-captured drift. The two-phase mechanism is separately covered by runtime and backend refusal tests; it does not enlarge those bounded application results. | | Citrix / VDI backend | **Supported** | The dedicated `--backend citrix` path selects the exact Citrix Workspace/Viewer owner, optionally binds an exact title, requires a readiness marker for governed `run`, carries the closed target into durable resume, and uses the shared pixel identity, effect, policy, and halt contracts. Consequential input reacquires the exact client window, focus, geometry, readiness, fresh pixels, resolved target, and record identity, then refuses any change before the first input edge. The accepted no-DOM qualification completed 3/3 healthy effects and 3/3 severe-drift safe-halts with 0 model calls, silent incorrect successes, false completions, healthy over-halts, or drift writes. Review the [immutable report](https://github.com/OpenAdaptAI/openadapt-flow/blob/f6faac5b900b78cbda5980de0e983a9f987285ac/benchmark/citrix_workspace/results.json), [Flow PR #183](https://github.com/OpenAdaptAI/openadapt-flow/pull/183), and [Flow PR #238](https://github.com/OpenAdaptAI/openadapt-flow/pull/238). | The accepted artifact explicitly records `code_readiness_accepted: true` and `ica_hdx_accepted: false`. It qualifies the shipped Citrix Workspace-window backend contract over a no-DOM canvas stand-in, not a counted real ICA/HDX batch. The exact ICA/HDX client, codec, latency, DPI, lock/readiness, input, identity, and effect matrix is a separate per-deployment qualification boundary. | -| Desktop authoring GUI and tray | **Supported / Beta** | Public `desktop-v0.14.0` provides Windows MSI/NSIS, macOS arm64/x64 DMG, and Linux AppImage/DEB installers. All six installer paths were installed, launched, and uninstalled in the native release workflow; the release includes `SHA256SUMS`, a CycloneDX SBOM, per-platform metadata, and build-provenance attestations. | Windows/Linux remain unsigned and macOS is ad-hoc signed, so verify checksums and provenance before overriding the OS publisher warning. The app and CLI drive the same released compiler/runtime. | +| Desktop authoring GUI and tray | **Supported / Beta** | Public `desktop-v0.15.0` provides Windows MSI/NSIS, macOS arm64/x64 DMG, and Linux AppImage/DEB installers. All six installer paths were installed, launched, and uninstalled in the native release workflow; the release includes `SHA256SUMS`, a CycloneDX SBOM, per-platform metadata, and build-provenance attestations. | Windows/Linux remain unsigned and macOS is ad-hoc signed, so verify checksums and provenance before overriding the OS publisher warning. The app and CLI drive the same released compiler/runtime. | | Hosted CLI connectivity | **Supported / public offer** | `login`, exact-hash artifact preparation/upload, one-time runtime validation, bound replacement activation, and `report-break` connect the local engine to the live control plane. | Upload requires destination policy and an approved sanitized derivative; checkout never bypasses an egress refusal. | | Artifact sanitation and local review | **Supported / launch gate** | The sanitized-derivative pipeline inventories, transforms, rescans, manifests, hashes, and supports local review/approval. | The raw original remains sensitive; unknown or unresolved content is refused; runtime observations can reintroduce PHI/PII. | | Cross-engine hosted validation | **Supported / launch gate** | `validate-hosted` binds an approved recording and bundle, compiler provenance, strict lint, policy certification, derived risk class, and successful replay report to a one-time Cloud challenge. | It is operator self-attestation signed with the ingest token, not an independently observed certification. Exact deployment policy, risk-class, and deployed compiler-version allowlists still apply. | diff --git a/docs/guides/security-and-data-handling.md b/docs/guides/security-and-data-handling.md index ca00d3e..ec50753 100644 --- a/docs/guides/security-and-data-handling.md +++ b/docs/guides/security-and-data-handling.md @@ -262,13 +262,13 @@ configured retention component separately from this destructive-operation gate. ## Release integrity -The public Desktop `desktop-v0.14.0` release includes Windows, macOS, and Linux +The public Desktop `desktop-v0.15.0` release includes Windows, macOS, and Linux installers, `SHA256SUMS`, a CycloneDX SBOM, per-platform metadata, and GitHub build-provenance attestations. These prove source and build provenance, not publisher identity. Windows and Linux installers remain unsigned and macOS installers are ad-hoc signed; Apple Developer ID/notarization and Windows Authenticode require the corresponding external identities. Verify the -[release assets](https://github.com/OpenAdaptAI/openadapt-desktop/releases/tag/desktop-v0.14.0) +[release assets](https://github.com/OpenAdaptAI/openadapt-desktop/releases/tag/desktop-v0.15.0) before overriding an operating-system publisher warning. ## Deployment options diff --git a/docs/guides/security-review.md b/docs/guides/security-review.md index a4d0461..a911b65 100644 --- a/docs/guides/security-review.md +++ b/docs/guides/security-review.md @@ -178,7 +178,7 @@ execution](hosted.md) and [Qualification evidence](../get-started/what-works-tod ## Release and secure-development evidence Python releases publish immutable wheel and sdist artifacts with PyPI -provenance attestations. Desktop `desktop-v0.14.0` publishes its complete +provenance attestations. Desktop `desktop-v0.15.0` publishes its complete Windows, macOS, and Linux installer set with checksums, a CycloneDX SBOM, per-platform metadata, and GitHub build-provenance attestations. The native installers are still unsigned on Windows/Linux and ad-hoc signed on macOS; diff --git a/docs/reference/compatibility.md b/docs/reference/compatibility.md index 6000337..f011fdd 100644 --- a/docs/reference/compatibility.md +++ b/docs/reference/compatibility.md @@ -20,7 +20,8 @@ not a separate product onboarding path. | `openadapt-flow` 1.x + native capture | `openadapt-capture >=1.1.0` | Canonical native demonstration recording for Windows, macOS, Linux, RDP, and Citrix | | Windows action-time UIA handoff | `openadapt-flow >=1.22,<2` + `openadapt-capture >=1.1.0` | Retains the nearest actionable UIA node for native Windows compilation; RDP and Citrix remain externally black-box | | `openadapt-flow` 1.x + privacy extra | `openadapt-privacy[presidio] >=1.0` | Configured local scrub/redaction paths | -| `openadapt-flow` interoperability extra | `openadapt-types >=0.2,<0.4` | Contributor-facing schema boundary | +| `openadapt-flow` 1.27.x interoperability and console extras | `openadapt-types >=0.7,<0.8` | Field-exact runtime overlay and attended-decision boundary tested by Flow | +| OpenAdapt Execute reference clients | `openadapt-types >=0.9,<0.10` | Async Execute request, status, webhook, and receipt contracts for approved private pilots | | Python | 3.10-3.12 | Supported runtime range for the current 1.x line | The package metadata is the executable source of truth for these ranges. CI @@ -31,8 +32,10 @@ and release archives are validated before publication. - Public launcher and engine APIs follow semantic versioning. Breaking CLI, bundle, or runtime-contract changes are reserved for a major release. -- Optional 0.x schema packages may break at a minor release, so the engine pins - an upper bound and raises it only after its interoperability suite passes. +- Optional 0.x schema packages may break at a minor release. Each consumer pins + the exact minor contract that it tests. Flow 1.27.x uses the 0.7 contract; + Execute clients use the 0.9 contract. Do not substitute one range for the + other. - Patch releases may ship immediately for security, safety, packaging, or installation defects. Routine capability changes should be consolidated so adopters see product releases rather than repository-level merge noise. diff --git a/mkdocs.yml b/mkdocs.yml index a4fdb45..f604ca2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -119,9 +119,9 @@ nav: - Home: index.md - Start: - get-started/index.md - - Install and first run: desktop/install.md - Your first workflow: get-started/first-workflow.md - What you get: get-started/what-you-get.md + - Desktop application: desktop/install.md - Build: - concepts/index.md - All how-to guides: guides/index.md