feat(quickstart): show it once, run it, break it

CAPABILITIES.md

@@ -249,7 +249,7 @@ improvising or retrying when something is off.
 | See a compiled program as a map (every step, exact edge, loop and stop rule, with each step's checks) and play a recorded run over it; one React package that Desktop, app.openadapt.ai and openadapt.ai share | On main ([packages/program-graph](packages/program-graph/README.md)) | Real compiled OpenEMR referral program and a recorded scoreboard run, both on synthetic data | `@openadapt/program-graph`; `openadapt-flow visualize --format json` |
 | Encrypt PHI at rest: every bundle file that can hold patient data under one sealed index (unknown files refused), web recordings from the first frame, and the run directories of sealed bundles; compile, induce, scaffold-verifier, qualify, admit, run, resume and undo read them in memory and refuse without the key | On main | Synthetic (no-plaintext audit-hook test over record, compile and a VERIFIED run; per-frame cost measured) | `openadapt-flow seal`, `record`; [phi_at_rest.md](packages/flow/docs/phi_at_rest.md) |
 | Signed receipts (Seals), countersigned and timestamped, offline by default | Released | Unit tests, real TSA tokens | `openadapt-flow seal`, `countersign`, `local-seal` |
-| Offline Seals signed with a key the customer holds: a key file, the OS keychain, or a PKCS#11 token or HSM; pinned keys with rotation and revocation; no fallback to a generated key | On main ([#1392](https://github.com/OpenAdaptAI/OpenAdapt/pull/1392)) | Unit tests with synthetic data (keychain and PKCS#11 through stand-ins) | `openadapt-flow local-seal --key`, `local-seal key create`, `pin`, `revoke`; [OFFLINE_SEALS.md](packages/flow/docs/OFFLINE_SEALS.md#customer-held-keys) |
+| Offline Seals signed with a key the customer holds: a key file, the OS keychain, or a PKCS#11 token or HSM; pinned keys with rotation and revocation; no fallback to a generated key | On main ([#1392](https://github.com/OpenAdaptAI/OpenAdapt/pull/1392)) | Unit tests with synthetic data (keychain and PKCS#11 through stand-ins) | `openadapt-flow local-seal --key`, `local-seal key create`, `pin`, `revoke`; `openadapt seal verify FOLDER` checks every sealed run in a folder; [OFFLINE_SEALS.md](packages/flow/docs/OFFLINE_SEALS.md#customer-held-keys) |
 | Anchor an offline Seal in the public Sigstore Rekor transparency log (opt-in; sends one digest and the public key), and verify the anchor offline from the stored inclusion proof | On main ([#1394](https://github.com/OpenAdaptAI/OpenAdapt/pull/1394)) | Unit tests against a simulated Rekor log; Ed25519ph matches the RFC 8032 test vector | `openadapt-flow local-seal anchor`, `local-seal verify --require-anchor`; [OFFLINE_SEALS.md](packages/flow/docs/OFFLINE_SEALS.md#optional-anchor-a-seal-in-a-public-transparency-log) |
 | Strict no-outbound mode and an unattended on-prem service | Released | Synthetic | `openadapt-flow no-outbound`, `service`; [ON_PREM.md](packages/flow/docs/ON_PREM.md) |
 

docs/quickstart/README.md

@@ -0,0 +1,12 @@
+# Quickstart capture and timing
+
+- `quickstart.gif`: `openadapt quickstart` start to finish, recorded with
+  [VHS](https://github.com/charmbracelet/vhs) from `quickstart.tape`. The
+  browser is hidden in the recording; the output is otherwise the real command
+  at real speed. Re-record with
+  `PATH="$PWD/.venv/bin:$PATH" vhs docs/quickstart/quickstart.tape`.
+- `inline-screenshot.png`: the third act on a terminal that draws images
+  (WezTerm), with the halted run's screenshot beside the database's answer.
+- `timing-2026-10-20.json`: the engine tutorial with `--break-it` (what
+  `openadapt quickstart --break-it` ran before) against the new quickstart,
+  three rounds each, interleaved, from `scripts/quickstart_timing.py`.

docs/quickstart/quickstart.tape

@@ -0,0 +1,33 @@
+# Records docs/quickstart/quickstart.gif with VHS (https://github.com/charmbracelet/vhs, MIT).
+#
+#   PATH="$PWD/.venv/bin:$PATH" vhs docs/quickstart/quickstart.tape
+#
+# The browser stays hidden (no display in the recording) and the side-by-side
+# page is not opened, so nothing appears outside the terminal. Everything else
+# is the real command, start to finish, at real speed.
+
+Output docs/quickstart/quickstart.gif
+
+Set Shell bash
+Set FontSize 15
+Set Width 1240
+Set Height 1060
+Set Padding 24
+Set Framerate 24
+Set TypingSpeed 45ms
+Set Theme "Builtin Dark"
+
+Hide
+Type "unset DISPLAY WAYLAND_DISPLAY; export SSH_CONNECTION=recording BROWSER=true OPENADAPT_SEAL_HOME=$(mktemp -d) PS1='$ '; cd $(mktemp -d) && clear"
+Enter
+Show
+
+Sleep 500ms
+Type "openadapt quickstart"
+Sleep 400ms
+Enter
+Wait+Screen@180s /Press Enter/
+Sleep 2s
+Enter
+Wait+Screen@180s /Give your agent/
+Sleep 6s

docs/quickstart/timing-2026-10-20-parallel.json

@@ -0,0 +1,94 @@
+{
+  "machine": "Darwin arm64",
+  "python": "3.12.13",
+  "commands": {
+    "before": "flow tutorial --break-it --out",
+    "after": "quickstart --headless --out"
+  },
+  "runs": [
+    {
+      "command": "before",
+      "round": 0,
+      "exit_code": 0,
+      "wall_s": 21.6,
+      "load_1m": 9.3,
+      "lines": 54
+    },
+    {
+      "command": "after",
+      "round": 0,
+      "exit_code": 0,
+      "wall_s": 22.58,
+      "load_1m": 10.0,
+      "lines": 39
+    },
+    {
+      "command": "before",
+      "round": 1,
+      "exit_code": 0,
+      "wall_s": 21.02,
+      "load_1m": 9.8,
+      "lines": 54
+    },
+    {
+      "command": "after",
+      "round": 1,
+      "exit_code": 0,
+      "wall_s": 22.09,
+      "load_1m": 9.7,
+      "lines": 39
+    },
+    {
+      "command": "before",
+      "round": 2,
+      "exit_code": 0,
+      "wall_s": 22.26,
+      "load_1m": 10.3,
+      "lines": 54
+    },
+    {
+      "command": "after",
+      "round": 2,
+      "exit_code": 0,
+      "wall_s": 22.31,
+      "load_1m": 30.5,
+      "lines": 39
+    },
+    {
+      "command": "before",
+      "round": 3,
+      "exit_code": 0,
+      "wall_s": 21.45,
+      "load_1m": 25.8,
+      "lines": 54
+    },
+    {
+      "command": "after",
+      "round": 3,
+      "exit_code": 0,
+      "wall_s": 21.56,
+      "load_1m": 28.4,
+      "lines": 39
+    },
+    {
+      "command": "before",
+      "round": 4,
+      "exit_code": 0,
+      "wall_s": 22.95,
+      "load_1m": 33.9,
+      "lines": 54
+    },
+    {
+      "command": "after",
+      "round": 4,
+      "exit_code": 0,
+      "wall_s": 24.19,
+      "load_1m": 35.9,
+      "lines": 39
+    }
+  ],
+  "median_wall_s": {
+    "before": 21.6,
+    "after": 22.31
+  }
+}

docs/quickstart/timing-2026-10-20.json

@@ -0,0 +1,62 @@
+{
+  "machine": "Darwin arm64",
+  "python": "3.12.13",
+  "commands": {
+    "before": "flow tutorial --break-it --out",
+    "after": "quickstart --headless --out"
+  },
+  "runs": [
+    {
+      "command": "before",
+      "round": 0,
+      "exit_code": 0,
+      "wall_s": 21.11,
+      "load_1m": 19.1,
+      "lines": 54
+    },
+    {
+      "command": "after",
+      "round": 0,
+      "exit_code": 0,
+      "wall_s": 31.44,
+      "load_1m": 22.9,
+      "lines": 40
+    },
+    {
+      "command": "before",
+      "round": 1,
+      "exit_code": 0,
+      "wall_s": 23.01,
+      "load_1m": 37.6,
+      "lines": 54
+    },
+    {
+      "command": "after",
+      "round": 1,
+      "exit_code": 0,
+      "wall_s": 40.22,
+      "load_1m": 46.8,
+      "lines": 39
+    },
+    {
+      "command": "before",
+      "round": 2,
+      "exit_code": 0,
+      "wall_s": 22.12,
+      "load_1m": 36.7,
+      "lines": 54
+    },
+    {
+      "command": "after",
+      "round": 2,
+      "exit_code": 0,
+      "wall_s": 32.87,
+      "load_1m": 27.4,
+      "lines": 39
+    }
+  ],
+  "median_wall_s": {
+    "before": 22.12,
+    "after": 32.87
+  }
+}

llms-full.txt

@@ -645,7 +645,7 @@ improvising or retrying when something is off.
 | See a compiled program as a map (every step, exact edge, loop and stop rule, with each step's checks) and play a recorded run over it; one React package that Desktop, app.openadapt.ai and openadapt.ai share | On main ([packages/program-graph](https://github.com/OpenAdaptAI/OpenAdapt/blob/main/packages/program-graph/README.md)) | Real compiled OpenEMR referral program and a recorded scoreboard run, both on synthetic data | `@openadapt/program-graph`; `openadapt-flow visualize --format json` |
 | Encrypt PHI at rest: every bundle file that can hold patient data under one sealed index (unknown files refused), web recordings from the first frame, and the run directories of sealed bundles; compile, induce, scaffold-verifier, qualify, admit, run, resume and undo read them in memory and refuse without the key | On main | Synthetic (no-plaintext audit-hook test over record, compile and a VERIFIED run; per-frame cost measured) | `openadapt-flow seal`, `record`; [phi_at_rest.md](https://github.com/OpenAdaptAI/OpenAdapt/blob/main/packages/flow/docs/phi_at_rest.md) |
 | Signed receipts (Seals), countersigned and timestamped, offline by default | Released | Unit tests, real TSA tokens | `openadapt-flow seal`, `countersign`, `local-seal` |
-| Offline Seals signed with a key the customer holds: a key file, the OS keychain, or a PKCS#11 token or HSM; pinned keys with rotation and revocation; no fallback to a generated key | On main ([#1392](https://github.com/OpenAdaptAI/OpenAdapt/pull/1392)) | Unit tests with synthetic data (keychain and PKCS#11 through stand-ins) | `openadapt-flow local-seal --key`, `local-seal key create`, `pin`, `revoke`; [OFFLINE_SEALS.md](https://github.com/OpenAdaptAI/OpenAdapt/blob/main/packages/flow/docs/OFFLINE_SEALS.md#customer-held-keys) |
+| Offline Seals signed with a key the customer holds: a key file, the OS keychain, or a PKCS#11 token or HSM; pinned keys with rotation and revocation; no fallback to a generated key | On main ([#1392](https://github.com/OpenAdaptAI/OpenAdapt/pull/1392)) | Unit tests with synthetic data (keychain and PKCS#11 through stand-ins) | `openadapt-flow local-seal --key`, `local-seal key create`, `pin`, `revoke`; `openadapt seal verify FOLDER` checks every sealed run in a folder; [OFFLINE_SEALS.md](https://github.com/OpenAdaptAI/OpenAdapt/blob/main/packages/flow/docs/OFFLINE_SEALS.md#customer-held-keys) |
 | Anchor an offline Seal in the public Sigstore Rekor transparency log (opt-in; sends one digest and the public key), and verify the anchor offline from the stored inclusion proof | On main ([#1394](https://github.com/OpenAdaptAI/OpenAdapt/pull/1394)) | Unit tests against a simulated Rekor log; Ed25519ph matches the RFC 8032 test vector | `openadapt-flow local-seal anchor`, `local-seal verify --require-anchor`; [OFFLINE_SEALS.md](https://github.com/OpenAdaptAI/OpenAdapt/blob/main/packages/flow/docs/OFFLINE_SEALS.md#optional-anchor-a-seal-in-a-public-transparency-log) |
 | Strict no-outbound mode and an unattended on-prem service | Released | Synthetic | `openadapt-flow no-outbound`, `service`; [ON_PREM.md](https://github.com/OpenAdaptAI/OpenAdapt/blob/main/packages/flow/docs/ON_PREM.md) |