diff --git a/docs/get-started/index.md b/docs/get-started/index.md index c9b71cc..a2613b5 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -1,47 +1,42 @@ --- description: >- - Install OpenAdapt, complete a verified local tutorial, and choose the next - guide for browser, desktop, RDP, Citrix, or production use. + Install OpenAdapt, run the MockMed tutorial, watch --break-it halt a fake + success, then record one read-only workflow. --- # Get started -Start with one complete local result. You do not need to understand the package -layout first. The tutorial records a demonstration, compiles it into a program, -runs the program, and verifies the saved result. - -
- ![An openIMIS eligibility check: a recorded demonstration, a verified replay, and a replay that halts.](../assets/showcase/demo.gif){ width="900" } -
A reference run against openIMIS 25.10 on synthetic data. It shows one - recorded eligibility check, then the compiled program replaying that check - twice. A read-only SQL query verifies the first replay and contradicts the - second, so the second one halts. The tutorial below runs the same loop against - a browser page.
-
- -See it working before you install anything: - -- **[Hosted demo](https://app.openadapt.ai/demo)**: recorded demonstrations, - verified replays, and fail-safe halts on real footage. -- **[Template gallery](https://openadapt.ai/templates)**: ready-to-adapt - workflow templates. -- **[Blog](https://blog.openadapt.ai)**: guides, updates, and automation - recipes. - -## First success: install, then run - You need no account, target application, API key, or operating-system -automation permission. - -**Recommended: install with pip.** Use an active Python 3.10–3.12 virtual -environment when your system manages Python packages. The base package includes -the browser driver used by the tutorial: +automation permission. Python 3.10 through 3.12. ```bash python -m pip install --upgrade openadapt openadapt quickstart +openadapt quickstart --break-it ``` +Add `--headed` if you want to watch the browser. + +The bundled workflow is a tutorial. Qualifying a real one means declaring its +application boundary, its action risks, its identities, its effect verifiers, +its fault cases, and its deployment policy. + +`openadapt quickstart` records a task in MockMed, a synthetic +practice-management fixture, compiles the observed +[effect contract](../reference/glossary.md#effect-contract), certifies it with +the shipped clinical-write [policy](../reference/glossary.md#policy), and runs +it under the Standard [profile](../reference/glossary.md#profile). A separate +read-only API confirms the saved record outside the screen that performed the +write. The healthy run returns [`VERIFIED`](../reference/run-outcomes.md) with +no model or Cloud call. + +`--break-it` is the aha. Same certified bundle. The backend rejects the write +after the app has already painted its success banner, so every on-screen check +passes and the run halts anyway, because the independent read disagrees. The +store is unchanged. + +OpenAdapt refuses to overwrite `openadapt-quickstart/`. Artifacts land there. + **Isolated CLI alternative.** The public installer creates and maintains an isolated environment with [uv](https://docs.astral.sh/uv/): @@ -52,14 +47,20 @@ curl -fsSL https://openadapt.ai/install.sh | sh Both paths install the same `openadapt` command. You need no package extra for the browser tutorial. -`openadapt quickstart` records the bundled synthetic MockMed task, compiles its -observed [effect contract](../reference/glossary.md#effect-contract), certifies -it with the shipped clinical-write [policy](../reference/glossary.md#policy), -and runs it under the Standard [profile](../reference/glossary.md#profile). A -separate read-only API confirms the saved record outside the screen that -performed the write. The healthy run returns -[`VERIFIED`](../reference/run-outcomes.md) with no model or Cloud call. Artifacts -go to `openadapt-quickstart/`. OpenAdapt refuses to overwrite that directory. +## The receipt you just got + +Tutorial `VERIFIED` is a local receipt on synthetic MockMed. It is not a +production Seal. `--break-it` is the aha: the banner can lie, and the +independent read stops the run. When you qualify a real job, that same +independent check is what a Seal attests. Public synthetic verify lives at +[openadapt.ai/seals](https://openadapt.ai/seals). The contract is +[The Seal](../commercial/seal.md). + +A production Seal needs a qualified program and an oracle at tier 2 or 3. +Oracle tiers 0 (visual) and 1 (second-session UI) never mint one. Local +unsigned replay stays free. + +## What the healthy run wrote You now have: @@ -83,53 +84,69 @@ Open `graph.html` in a browser. That page is the compiled program: the steps it can take, the evidence each one needs, and the paths that stop the run. See [Read a compiled program](../concepts/program-visualizer.md). -The tutorial receipt is local and unsigned. Anyone who has to believe the run -needs a Seal. On a qualified synthetic bundle with a tier-2 oracle, the -intended command is: - -```bash -openadapt-flow replay bundle --seal -``` - -A sealed verified run prints `VERIFIED`, a seal id, and a public verify URL: +!!! 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, + application, and local system of record. A customer workflow must bind its + own application, execution surface, action risks, identity checks, + independent effect verifier, fault cases, and deployment policy. -```text -VERIFIED -seal_id receipt_12345678 -verify https://openadapt.ai/seals/receipt_12345678 -``` +## What qualifying a real job adds -`--seal` on replay issues that proof. `openadapt flow seal` encrypts a bundle -for deployment. Public `/seals/` pages list synthetic fixtures. They do not -list healthcare production. Oracle tiers 0 (visual) and 1 (second-session UI) -never mint a production Seal. See [The Seal](../commercial/seal.md). +Qualification tests the workflow against real failures in its environment +before it runs. You declare: -When you move from the tutorial to your own work, qualification tests the -workflow against real failures in its environment before it runs. +- the application boundary +- the action risks +- the identities +- the effect verifiers +- the fault cases +- the deployment policy -After the first run, choose the path that matches your goal: +Start with one real, read-only task. Don't start with a write. | Goal | Next guide | |---|---| | Record one real, read-only browser workflow | [Your first workflow](first-workflow.md) | | See what the compiled program looks like | [Read a compiled program](../concepts/program-visualizer.md) | -| Issue a Seal on a synthetic run | [The Seal](../commercial/seal.md) | +| Bind identity, effects, faults, and policy | [Qualify a workflow](../guides/qualify-a-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, - application, and local system of record. A customer workflow must bind its - own application, execution surface, action risks, identity checks, - independent effect verifier, fault cases, and deployment policy. +
+ ![An openIMIS eligibility check: a recorded demonstration, a verified replay, and a replay that halts.](../assets/showcase/demo.gif){ width="900" } +
The same loop against openIMIS 25.10 on synthetic data. One + recorded eligibility check, then the compiled program replaying that check + twice. A read-only SQL query verifies the first replay and contradicts the + second, so the second one halts.
+
+ +Want to watch before you record your own app? + +- **[Hosted demo](https://app.openadapt.ai/demo)**: recorded demonstrations, + verified replays, and fail-safe halts on real footage. +- **[Template gallery](https://openadapt.ai/templates)**: ready-to-adapt + workflow templates. +- **[Blog](https://blog.openadapt.ai)**: guides, updates, and automation + recipes. + +## First real (read-only) workflow + +[Your first workflow](first-workflow.md) records one small real task that +doesn't change business data. A read-only lookup against test data works. +Open a known test record, then stop when a field shows the expected value. + +Don't start with a task that saves, submits, creates, or deletes data. A +write waits until qualification binds its risks, identities, and effect +verifiers. -## See a fail-safe halt +## See a fail-safe halt from UI drift -Use the compiled tutorial bundle in an ordinary Demo-profile replay. This path -has no independent verifier, so OpenAdapt must not reuse the Standard -`VERIFIED` result: +`--break-it` already showed a painted success that failed the independent +read. Theme drift is a different halt. Use the compiled tutorial bundle in an +ordinary Demo-profile replay. This path has no independent verifier, so +OpenAdapt must not reuse the Standard `VERIFIED` result: ```bash openadapt flow replay openadapt-quickstart/bundle \ diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index c9701d5..87566a4 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -15,8 +15,9 @@ This URL is from an older docs tree. Start at [Get started](/get-started/). ```bash pip install openadapt openadapt quickstart +openadapt quickstart --break-it ``` -`openadapt quickstart` records a demonstration, compiles it, and replays the program. For your own app, use `openadapt flow record`, `compile`, and `replay`. +`openadapt quickstart` records a demonstration, compiles it, and replays the program. `--break-it` is the halt demo. For your own app, use `openadapt flow record`, `compile`, and `replay`. [Continue to Get started](/get-started/){ .md-button .md-button--primary } diff --git a/docs/index.md b/docs/index.md index 3d86e7b..fc6a5e1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -150,7 +150,8 @@ report determine its outcome. - [__Try the local tutorial__](get-started/index.md) - Install OpenAdapt and produce a verified local result with two commands. + Install OpenAdapt, run `openadapt quickstart`, then + `openadapt quickstart --break-it`. - [__Record your application__](get-started/first-workflow.md) diff --git a/docs/llms.txt b/docs/llms.txt index d846228..9399b96 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -3,7 +3,7 @@ > Official documentation for OpenAdapt, an open-source demonstration compiler for repeated GUI work. Record a GUI workflow once and compile it into deterministic replay: healthy runs are local and make no generative-model API calls; under UI drift the runtime re-resolves from retained evidence, proposes governed repairs, accepts human teaching, or halts rather than guess. MIT licensed. ## Get started -- [Get started](https://docs.openadapt.ai/get-started/): Run `pip install openadapt`, then `openadapt quickstart` for a complete local, effect-verified tutorial. The current CLI is `openadapt flow record`, `compile`, `replay`. Older `/getting-started/` and package-mirror URLs redirect here. +- [Get started](https://docs.openadapt.ai/get-started/): Run `pip install openadapt`, then `openadapt quickstart`, then `openadapt quickstart --break-it`. The bundled workflow is a tutorial. The current CLI is `openadapt flow record`, `compile`, `replay`. Older `/getting-started/` URLs and the `/start/` alias redirect here. - [Qualification evidence](https://docs.openadapt.ai/get-started/what-works-today/): Accepted substrate results, exact environments, and deployment boundaries - [Your first workflow](https://docs.openadapt.ai/get-started/first-workflow/): Install the base package, then record, compile, lint, replay, and read the report on your own web app - [What you get](https://docs.openadapt.ai/get-started/what-you-get/): The workflow bundle, the run report, and what each artifact is for diff --git a/docs/start/index.md b/docs/start/index.md new file mode 100644 index 0000000..0a8580e --- /dev/null +++ b/docs/start/index.md @@ -0,0 +1,23 @@ +--- +title: Start moved +description: Install OpenAdapt and run the current record, compile, replay tutorial. +canonical: https://docs.openadapt.ai/get-started/ +redirect_to: /get-started/ +search: + exclude: true +hide: + - navigation + - toc +--- + +# Start moved + +This URL is an alias. The walkthrough is [Get started](/get-started/). + +```bash +pip install openadapt +openadapt quickstart +openadapt quickstart --break-it +``` + +The bundled workflow is a tutorial. [Continue to Get started](/get-started/){ .md-button .md-button--primary } diff --git a/mkdocs.yml b/mkdocs.yml index fab44f3..15fc40e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -123,6 +123,10 @@ extra: # Start, Build, Operate, Security, Internals. Pages keep their existing # on-disk paths (get-started/, concepts/, guides/, reference/, desktop/, # ecosystem/); only their grouping and cross-links change. +# +# Guessed-path alias. Built so /start/ redirects; keep it off the nav. +not_in_nav: | + /start/index.md nav: - Home: index.md - Start: diff --git a/scripts/validate_docs.py b/scripts/validate_docs.py index 7824c75..261dbff 100644 --- a/scripts/validate_docs.py +++ b/scripts/validate_docs.py @@ -14,6 +14,13 @@ REQUIRED_PUBLIC_PAGES = { "index.md": ("reference/production-lifecycle.md",), "ecosystem/index.md": ("data-openadapt-production-target",), + "get-started/index.md": ( + "pip install", + "openadapt quickstart", + "--break-it", + "tutorial", + "first-workflow.md", + ), "get-started/what-works-today.md": ( "Qualification evidence", "Integrated product matrix", @@ -109,7 +116,9 @@ # Old docs.openadapt.ai URLs that taught capture-then-train or mirrored a # research README as if it were the product. Each file must keep serving a # Flow-first redirect so a crawler that still holds the URL drops the old -# snippet. Do not put these in the nav. +# snippet. Do not put these in the nav. `start/index.md` is a guessed-path +# alias, not a retired train-path page: people type /start on docs and must +# land on get-started, not a third onboarding tree. RETIRED_REDIRECTS = { "architecture.md": "/concepts/", "cli.md": "/reference/cli/", @@ -117,6 +126,7 @@ "getting-started/installation.md": "/get-started/", "getting-started/permissions.md": "/desktop/install/", "getting-started/quickstart.md": "/get-started/", + "start/index.md": "/get-started/", "LEGACY_FREEZE.md": "/get-started/", "legacy/freeze.md": "/get-started/", "packages/capture.md": "/ecosystem/", diff --git a/tests/test_validate_docs.py b/tests/test_validate_docs.py index e0d706b..174fb1a 100644 --- a/tests/test_validate_docs.py +++ b/tests/test_validate_docs.py @@ -81,8 +81,10 @@ def _write_contract_docs(root): "openadapt-evals is **Research**." ), "get-started/index.md": ( - "# Get started\n\nInstall with `pip install openadapt` and use " - "`openadapt flow`." + "# Get started\n\nInstall with `pip install openadapt`, then " + "`openadapt quickstart` and `openadapt quickstart --break-it`. " + "The bundled workflow is a tutorial. Continue in " + "[Your first workflow](first-workflow.md)." ), "get-started/first-workflow.md": ( "---\n"