From ee61e9465f90d310e46838084745b93105346a3a Mon Sep 17 00:00:00 2001 From: abrichr Date: Wed, 2 Sep 2026 11:36:44 -0400 Subject: [PATCH] docs: lead with flow tutorial as the VERIFIED first command openadapt flow tutorial is the launcher spelling of openadapt-flow tutorial. That is the command that writes a VERIFIED receipt. Keep openadapt quickstart --break-it as the halt demo. Record with openadapt flow record --out rec and no --backend. --- README.md | 36 ++++++++++++++++------------ docs/cli.md | 25 ++++++++++--------- docs/getting-started/installation.md | 2 +- docs/getting-started/quickstart.md | 23 ++++++++++-------- docs/packages/index.md | 2 +- openadapt/cli.py | 8 +++++-- tests/test_cli_smoke.py | 3 ++- 7 files changed, 58 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 81193c3a4..432777d95 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ the run tool: ```bash python -m pip install --upgrade openadapt -openadapt quickstart +openadapt flow tutorial openadapt-agent serve --allow-run ``` @@ -47,10 +47,11 @@ 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: /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-`). `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 /bundle --out graph.html +openadapt flow lint /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. diff --git a/docs/cli.md b/docs/cli.md index 050b25019..0b025ad7e 100644 --- a/docs/cli.md +++ b/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: diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 6fd0183d3..601908467 100644 --- a/docs/getting-started/installation.md +++ b/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 diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 161ca489c..c79f595e5 100644 --- a/docs/getting-started/quickstart.md +++ b/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 /bundle --out graph.html +openadapt flow lint /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 diff --git a/docs/packages/index.md b/docs/packages/index.md index c157fece5..f9296808e 100644 --- a/docs/packages/index.md +++ b/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: diff --git a/openadapt/cli.py b/openadapt/cli.py index dc018c393..e7ae9b902 100644 --- a/openadapt/cli.py +++ b/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 diff --git a/tests/test_cli_smoke.py b/tests/test_cli_smoke.py index f8f68eb68..cae3423bf 100644 --- a/tests/test_cli_smoke.py +++ b/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