docs: make get-started the onboarding walkthrough

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.
-
-<figure markdown="span">
-  ![An openIMIS eligibility check: a recorded demonstration, a verified replay, and a replay that halts.](../assets/showcase/demo.gif){ width="900" }
-  <figcaption>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.</figcaption>
-</figure>
-
-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.
+<figure markdown="span">
+  ![An openIMIS eligibility check: a recorded demonstration, a verified replay, and a replay that halts.](../assets/showcase/demo.gif){ width="900" }
+  <figcaption>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.</figcaption>
+</figure>
+
+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 \

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 }

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)
 

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

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 }

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:

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,14 +116,17 @@
 # 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/",
     "getting-started/index.md": "/get-started/",
     "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/",

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"