docs: lead with flow tutorial as the VERIFIED first command

README.md

@@ -39,18 +39,19 @@ the run tool:
 
 ```bash
 python -m pip install --upgrade openadapt
-openadapt quickstart
+openadapt flow tutorial
 openadapt-agent serve --allow-run
 ```
 
 Python 3.10 through 3.12. No account, no API key, no extra. Chromium downloads
 itself the first time a browser action runs. `openadapt-agent` is in the base
 install.
 
-`quickstart` records and compiles a task in MockMed, a synthetic
-practice-management fixture, certifies it against the shipped clinical-write
-policy, runs it under the Standard profile, then confirms the saved record
-through a read-only API that the screen doing the writing never touches:
+`openadapt flow tutorial` is the launcher spelling of `openadapt-flow tutorial`.
+It records and compiles a task in MockMed, a synthetic practice-management
+fixture, certifies it against the shipped clinical-write policy, runs it under
+the Standard profile, then confirms the saved record through a read-only API
+that the screen doing the writing never touches:
 
 ```
 [1/5] Record the demonstration against a real persistence boundary
@@ -61,18 +62,19 @@ through a read-only API that the screen doing the writing never touches:
       VERIFIED in 4.1s; 0 model calls; the system of record holds 1 record(s)
 [5/5] Emit the local run receipt
 
-VERIFIED: openadapt-quickstart/run/REPORT.md
+VERIFIED: <out>/run/REPORT.md
   transaction     VERIFIED
+  metering class  billable (this local tutorial was not reported or charged)
   profile         standard
   model calls     0
   effects         2/2 confirmed at evidence tier 1 (independent system of record)
 ```
 
-Real output from `openadapt` 1.16.0 on macOS, 2026-08-28, with absolute paths
-shortened. You now have `openadapt-quickstart/recording/` (the demonstration
-and its retained target evidence), `openadapt-quickstart/bundle/` (the compiled
-workflow, which you can read), and `openadapt-quickstart/run/` (the ordered
-actions, the evidence, and the outcome).
+That's real output from Flow 1.34.0 (launcher 1.16.0) on macOS, 2026-08-28,
+with the run directory shortened. The tutorial writes the recording, the
+compiled bundle, and the run receipt under its output directory (default
+`tutorials/tutorial-<UTC timestamp>`). `openadapt quickstart` is a wrapper
+around the same engine path. The `VERIFIED` receipt comes from `tutorial`.
 
 Then watch it refuse to lie to you:
 
@@ -105,19 +107,23 @@ Seal; treat unsigned production success as failure.
 Inspect what compiled, and what it failed to cover:
 
 ```bash
-openadapt flow visualize openadapt-quickstart/bundle --out graph.html
-openadapt flow lint openadapt-quickstart/bundle
+openadapt flow visualize <out>/bundle --out graph.html
+openadapt flow lint <out>/bundle
 ```
 
 ## Author a workflow
 
+Do not pass `--backend`. With no `--url`, record captures this OS. Pass
+`--url` when the surface is a browser.
+
 ```bash
-openadapt flow record --backend web --url https://your-app.example --out rec
+openadapt flow record --out rec
+openadapt flow record --url https://your-app.example --out rec
 openadapt flow compile rec --out bundle --name my-workflow
 openadapt flow replay bundle --url https://your-app.example --run-dir run
 ```
 
-These commands record one browser surface and run a permissive local rehearsal.
+These commands record one surface and run a permissive local rehearsal.
 They do not certify the bundle. One bundle uses one execution surface and does
 not switch between browser, native, RDP, or Citrix backends.
 

docs/cli.md

@@ -11,17 +11,18 @@ installed `openadapt-flow` engine.
 
 ```bash
 python -m pip install --upgrade openadapt
-openadapt quickstart [--headed] [--break-it] [--out NEW_DIRECTORY]
+openadapt flow tutorial [--headed] [--break-it] [--out NEW_DIRECTORY]
 openadapt-agent serve --allow-run
 ```
 
-`quickstart` runs the bundled synthetic MockMed workflow from recording through
-an independently verified Standard-profile result. It refuses to overwrite an
-existing output directory. `--break-it` reruns the same certified bundle
-against a lying backend; the independent oracle must HALT and leave the store
-unchanged. `openadapt-agent serve --allow-run` then generates the public
-MockMed bundle at serve time and hosts it over MCP. A client POSTs authorized
-work and gets a receipt. Frames stay on this machine.
+`openadapt flow tutorial` is the command that writes a `VERIFIED` receipt. It
+runs the bundled synthetic MockMed workflow from recording through an
+independently verified Standard-profile result. `openadapt quickstart --break-it`
+is the halt demo: it reruns the same certified bundle against a lying backend,
+and the independent oracle must HALT and leave the store unchanged.
+`openadapt-agent serve --allow-run` then generates the public MockMed bundle at
+serve time and hosts it over MCP. A client POSTs authorized work and gets a
+receipt. Frames stay on this machine.
 
 ## Flow lifecycle
 
@@ -69,11 +70,13 @@ smoke gate. The replay uses the Demo profile and returns
 ## Record and replay one surface
 
 ```bash
-openadapt flow record --backend web --url https://your-app.example --out rec
-openadapt flow replay bundle --backend web \
-  --url https://your-app.example --run-dir run
+openadapt flow record --out rec
+openadapt flow record --url https://your-app.example --out rec
+openadapt flow replay bundle --url https://your-app.example --run-dir run
 ```
 
+Omit `--backend`. No `--url` records this OS. `--url` records the browser.
+
 Supported selectors are `web`, `windows`, `macos`, `linux`, `rdp`, and
 `citrix`. The required target flags differ by surface. Run these commands for
 the installed option contract:

docs/getting-started/installation.md

@@ -13,7 +13,7 @@ Install the launcher:
 
 ```bash
 python -m pip install --upgrade openadapt
-openadapt quickstart
+openadapt flow tutorial
 ```
 
 The launcher installs the compatible `openadapt-flow` engine. Do not install

docs/getting-started/quickstart.md

@@ -9,7 +9,7 @@ Use Python 3.10, 3.11, or 3.12:
 
 ```bash
 python -m pip install --upgrade openadapt
-openadapt quickstart
+openadapt flow tutorial
 ```
 
 The command runs one complete local lifecycle against synthetic MockMed data:
@@ -26,8 +26,8 @@ The healthy run returns `VERIFIED`. It makes no model or Cloud call.
 Inspect the artifacts:
 
 ```bash
-openadapt flow visualize openadapt-quickstart/bundle --out graph.html
-openadapt flow lint openadapt-quickstart/bundle
+openadapt flow visualize <out>/bundle --out graph.html
+openadapt flow lint <out>/bundle
 ```
 
 Run the same certified bundle against a fault-injecting backend:
@@ -56,17 +56,20 @@ The strict lint step returns a nonzero exit code. The bundled manual demo has
 an unarmed irreversible click. The permissive certification is only a smoke
 gate. The Demo replay returns `COMPLETED_UNVERIFIED`, not `VERIFIED`.
 
-Use `openadapt quickstart` for the effect-verified first run. For a real
-workflow, add the application boundary, action risks, identity requirements,
-effect verifier, fault cases, and deployment policy before production use.
+Use `openadapt flow tutorial` for the effect-verified first run.
+`openadapt quickstart --break-it` is the halt demo. For a real workflow, add
+the application boundary, action risks, identity requirements, effect verifier,
+fault cases, and deployment policy before production use.
 
-## Record a browser workflow
+## Record a workflow
+
+Omit `--backend`. No `--url` records this OS. `--url` records the browser.
 
 ```bash
-openadapt flow record --backend web --url https://your-app.example --out rec
+openadapt flow record --out rec
+openadapt flow record --url https://your-app.example --out rec
 openadapt flow compile rec --out bundle --name my-workflow
-openadapt flow replay bundle --backend web \
-  --url https://your-app.example --run-dir run
+openadapt flow replay bundle --url https://your-app.example --run-dir run
 ```
 
 Password fields and fields declared with `--secret` exclude their values at

docs/packages/index.md

@@ -19,7 +19,7 @@ Install the launcher and run the browser tutorial:
 
 ```bash
 python -m pip install --upgrade openadapt
-openadapt quickstart
+openadapt flow tutorial
 ```
 
 Install a native or remote capability:

openadapt/cli.py

@@ -62,7 +62,7 @@ def main():
     \b
     Quick Start:
         python -m pip install --upgrade openadapt
-        openadapt quickstart
+        openadapt flow tutorial
         openadapt-agent serve --allow-run
 
     \b
@@ -74,8 +74,12 @@ def main():
         openadapt flow replay bundle
 
     The manual demo is runnable but not certified for consequential work.
-    Use `openadapt quickstart` for the effect-verified first run.
+    Use `openadapt flow tutorial` for the effect-verified first run.
     `openadapt-agent serve --allow-run` then exposes run_* tools over MCP.
+
+    \b
+    Halt demo:
+        openadapt quickstart --break-it
     """
     pass
 

tests/test_cli_smoke.py

@@ -471,7 +471,8 @@ def test_top_level_help_leads_with_flow():
     assert result.exit_code == 0
     # Quick Start headline and Commands listing both lead with flow.
     assert "openadapt flow demo-record" in result.output
-    assert "openadapt quickstart" in result.output
+    assert "openadapt flow tutorial" in result.output
+    assert "openadapt quickstart --break-it" in result.output
     assert "openadapt-agent serve --allow-run" in result.output
     assert "effect-verified first run" in result.output
     assert "Standalone local human GUI capture" in result.output