Flows: follow named flows through a build, with named checkpoints that two runs pair up by

README.md

@@ -233,6 +233,44 @@ npx @expo/explore explore:session --replay steps.json   # an iPhone Duo pose, or
 
 </details>
 
+<details>
+<summary><strong>Follow named flows, step by step</strong></summary>
+
+A flow is a path through the app that you care about, such as signing in, or renaming a pattern. Name your flows and the checkpoints along each one, then pass them with `--flows`. Each flow starts from a relaunched app, and each checkpoint is photographed under its name, so two runs of the same flows (two builds, or an iPhone and an Android phone) line up checkpoint by checkpoint.
+
+```sh
+npx @expo/explore explore:binary ./my-app.app --flows flows.json
+```
+
+```json
+{
+  "flows": [
+    { "name": "Sign in", "steps": [
+      { "checkpoint": "Welcome" },
+      { "do": "Sign in with {{secret:TEST_EMAIL}} and {{secret:TEST_PASSWORD}}" },
+      { "checkpoint": "Home" }
+    ] },
+    { "name": "Dark mode", "steps": [
+      { "action": "tap", "label": "Settings" },
+      { "action": "tap", "label": "Dark" },
+      { "checkpoint": "Settings, dark" }
+    ] }
+  ]
+}
+```
+
+- A step is an exact action, written as in `--replay`; a step described in words (`"do"`); or a `"checkpoint"`. A model carries out each described step on its own, seeing only that step, and stops when the app shows it is done. An exact step needs no model, so a flows file with only exact steps runs without a model login.
+- `--provider`, `--model` and `--hints` steer the model that carries out described steps, and cannot be passed when there are none.
+- Flow names, and checkpoint names within a flow, must be unique: they are how two runs are paired. Every flow needs at least one checkpoint, and a flow with no checkpoint on the platform being run is skipped.
+- A step that fails ends its flow, as does a relaunch that fails or a checkpoint whose screen cannot be read. The report names why and goes on to the next flow; after two relaunches fail in a row, the run stops. A described step that hasn't finished after 40 tool calls fails.
+- A checkpoint on a screen that withholds its picture (it shows a secret, or the app blocks screenshots) is recorded without one, with why, and the flow goes on. The run's summary lists such checkpoints.
+- The report lists every flow and checkpoint of the file, in order, even those a run never reached: each one without a picture says why, so two runs still pair up step by step.
+- Each flow is also a journey of the map: the path its steps took, from the screen it started on. When the app moved without a tap the map could record (it left the app, or changed on its own), the path goes on as a second journey of the flow.
+- Relaunching ends the app's process, and the app keeps its data, so a flow that signs in leaves the next flow signed in. On `explore:session`, the app is relaunched before the first flow too.
+- A `{{secret:NAME}}` or a described step limited by `platforms` to another platform needs no value, and no model, on this one.
+
+</details>
+
 <details>
 <summary><strong>What a run without source shows</strong></summary>
 

skills/explore-binary/SKILL.md

@@ -37,6 +37,13 @@ Budgets default to 15 minutes, 40 screens, 150 actions (`--max-duration-minutes`
 
 To compare runs, or an iPhone with an Android phone, screen for screen, pass `--replay steps.json` to `explore:binary` or `explore:session`: Explore takes the steps in the file instead of a model's, and no model access is needed. The format is in the README ("Take the same steps on every run and device"): `{ "steps": [{ "capture": "Home" }, { "action": "tap", "label": "Settings" }, { "capture": "Settings" }] }`, with `platforms` to limit a step and `optional` for an action that may fail. The plan is checked before a device starts: unknown fields, a plan with no steps for the platform, more captures or actions than `--max-screens` / `--max-actions`, and a `{{secret:NAME}}` in a `fill` or `type` whose variable is not set are all refused (`REPLAY_PLAN_INVALID`, `REPLAY_PLAN_EMPTY`, `REPLAY_PLAN_OVER_BUDGET`, `EXPLORATION_SECRET_MISSING`). `--provider`, `--model` and `--hints` cannot be combined with it (`REPLAY_OPTIONS_IGNORED`).
 
+## Named flows: `--flows`
+
+When the user describes a flow, or a set of flows, to look at ("sign in, then rename a pattern"), write them as a flows file and pass `--flows flows.json`, not `--replay`. The format is in the README ("Follow named flows, step by step"): `{ "flows": [{ "name": "Sign in", "steps": [{ "checkpoint": "Welcome" }, { "do": "Sign in with {{secret:TEST_EMAIL}}" }, { "checkpoint": "Home" }] }] }`.
+- Each step is an exact action (the `--replay` format), a step described in words (`do`) that a model carries out, or a named `checkpoint`. Use exact actions where you know the labels, and `do` where you don't.
+- Each flow starts from a relaunched app, and its checkpoints are photographed under their names. `report/exploration.json` lists each flow under `exploration.flows`, with its status and its checkpoints in order, so two runs pair up by flow and checkpoint name. A checkpoint on a screen that withholds its picture (a secret on it) is listed with why it has none, and its flow goes on.
+- The file is checked before a device starts (`FLOWS_PLAN_INVALID`, `FLOWS_PLAN_EMPTY`, `FLOWS_PLAN_OVER_BUDGET`). `--provider`, `--model` and `--hints` steer the model that carries out `do` steps, and are refused when there are none (`FLOWS_OPTIONS_IGNORED`). `--flows` and `--replay` cannot be combined.
+
 ## Sign-in and other app state
 
 Without help, the model treats a sign-in wall as the end of the road: it captures it and stops (`blocked`). Before running, read what you can about the app (its source if you have it, its first screens otherwise) and decide what it needs.