kaloko 0.16.0 → 0.17.0

package/README.md

@@ -66,6 +66,13 @@ npx kaloko preview                    # local canvas
 npx kaloko share --pr                 # upload to kaloko.app, comment on the PR
 ```
 
+When a run belongs to a record outside Kaloko, say a change request in your QMS,
+name it at the start: `--ref CC-2026-001` (repeat it for more, or set
+`KALOKO_REFS` in CI) and, if you like, `--purpose dry_run`, `formal` or `smoke`
+(`KALOKO_PURPOSE`). The canvas shows both, and `npx kaloko runs --ref CC-2026-001`
+or `GET /api/v1/orgs/<org>/runs?ref=CC-2026-001` lists every run of that record
+with its verdict, environment and purpose.
+
 After a fix, walk only what the change reaches: `npx kaloko affected` explains
 which steps the changed files touch (routes, imports, `affects:` globs in the
 scenario), and `npx kaloko walk --affected` walks them. Several locales walk at

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Your AI agents build; Kaloko walks every screen, puts it on one canvas and records who approved what.",
   "keywords": [
     "qa",
@@ -32,7 +32,8 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node scripts/test.mjs"
+    "test": "node scripts/test.mjs",
+    "version": "node scripts/cli-catalogue.mjs && git add worker/src/cli-latest.json"
   },
   "dependencies": {
     "ajv": "^8.20.0",

package/schemas/evidence.v1.json

@@ -19,6 +19,18 @@
     "time": { "type": ["string", "null"], "description": "ISO 8601 time in UTC (…Z), from the service's clock." },
     "sha256": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$", "description": "SHA-256, lowercase hex." },
     "refs": { "type": "array", "items": { "type": "string" }, "description": "Requirement references as written in the scenario (refs:), free text, never interpreted." },
+    "session": {
+      "type": "object",
+      "description": "A person in the flow (a role): the key of the scenario's sessions: and its title.",
+      "required": ["key", "title"],
+      "properties": { "key": { "type": "string" }, "title": { "type": "string", "description": "The session's title (a localized title in its default or first language); the key when it has none." } }
+    },
+    "lane": {
+      "type": "object",
+      "description": "A lane of the canvas (a sub-process of the flow).",
+      "required": ["index", "label"],
+      "properties": { "index": { "type": "integer", "minimum": 0, "description": "The lane's number, from 0 (the canvas link #lane=<index>)." }, "label": { "type": ["string", "null"], "description": "The scenario's lanes: label, or the session's title when the sessions draw the lanes; null for an unnamed lane." } }
+    },
     "run": {
       "type": "object",
       "required": ["generated_at", "acceptance", "signing", "record", "run", "scenario", "steps", "signatures", "trace"],
@@ -57,7 +69,9 @@
             "started_at": { "$ref": "#/$defs/time", "description": "When the walk started (the walking machine's clock)." },
             "finished_at": { "$ref": "#/$defs/time", "description": "When the manifest was built (the walking machine's clock)." },
             "version": { "type": ["string", "null"], "description": "Design version, for runs of design environments." },
-            "app_version": { "type": ["string", "null"], "description": "Version of the application under test, when the run names one." }
+            "app_version": { "type": ["string", "null"], "description": "Version of the application under test, when the run names one." },
+            "refs": { "type": "array", "items": { "type": "string" }, "description": "External records the run serves, e.g. a change-control record (kaloko start --ref). Empty when the run names none, and for records made before runs carried them." },
+            "purpose": { "enum": ["dry_run", "formal", "smoke", null], "description": "Why the run was walked (kaloko start --purpose): a label, null when the run does not say." }
           }
         },
         "scenario": {
@@ -68,7 +82,9 @@
             "version": { "type": ["integer", "string", "null"], "description": "The scenario's own version: field, when set." },
             "file": { "type": ["string", "null"], "description": "Path of the scenario file in the repository." },
             "sha256": { "$ref": "#/$defs/sha256", "description": "SHA-256 of the scenario file as walked (CLI 0.15+; null before)." },
-            "refs": { "$ref": "#/$defs/refs" }
+            "refs": { "$ref": "#/$defs/refs" },
+            "lanes": { "type": ["array", "null"], "items": { "$ref": "#/$defs/lane" }, "description": "The flow's lanes (its sub-processes), in order: every named lane and every lane a step sits in. Named by the scenario's lanes:, or, without them, one per session. Null when the run's manifest could not be read." },
+            "sessions": { "type": ["array", "null"], "items": { "$ref": "#/$defs/session" }, "description": "The people in the flow (roles), in the scenario's order. Empty for a flow without sessions; null when the run's manifest could not be read." }
           }
         },
         "environment": { "type": ["object", "null"], "description": "{ name, url }: the environment and its base URL." },
@@ -101,6 +117,8 @@
               "title": { "type": ["string", "null"] },
               "refs": { "$ref": "#/$defs/refs" },
               "status": { "enum": ["pass", "partial", "fail", "skip"] },
+              "session": { "oneOf": [{ "$ref": "#/$defs/session" }, { "type": "null" }], "description": "The role that performs the step (the step's session:), or null." },
+              "lane": { "oneOf": [{ "$ref": "#/$defs/lane" }, { "type": "null" }], "description": "The lane the step sits in on the canvas (its sub-process); #lane=<index> on the canvas URL opens it." },
               "decision": { "type": ["object", "null"], "description": "The step's current decision: { id, state: approved | returned, by, at, via, agent?, counts_as_person, note?, attachments?: [{ id, name, type, bytes, sha256, by, at, path: decisions/<step>/<file> in the evidence package }], pin?, shape? }." },
               "decisions": { "type": "array", "description": "Every decision on the step, oldest first, shaped like decision; superseded ones too (resolved_at, deleted: true without content)." },
               "carried": { "type": ["object", "null"], "description": "An approval carried over from an earlier accepted run: { from_run, compared_run, kind, approved_by, approved_at, approved_via }." },
@@ -184,7 +202,7 @@
     },
     "traceRow": {
       "type": "object",
-      "description": "One row of the trace matrix: a requirement, a criterion, a step in one locale and viewport, its screenshot, the result and the decisions. A criterion's requirements are its own refs, its step's and its scenario's (requirement_level); a criterion without any gets one row with requirement null. The CSV has these columns in this order.",
+      "description": "One row of the trace matrix: a requirement, a criterion, a step in one locale and viewport with its role (session) and lane, its screenshot, the result and the decisions. A criterion's requirements are its own refs, its step's and its scenario's (requirement_level); a criterion without any gets one row with requirement null. The CSV has these columns in this order.",
       "properties": {
         "requirement": { "type": ["string", "null"] },
         "requirement_level": { "enum": ["criterion", "step", "scenario", null] },
@@ -220,7 +238,11 @@
         "run_signature_meaning": { "type": ["string", "null"] },
         "run_signer_name": { "type": ["string", "null"] },
         "run_signed_at": { "$ref": "#/$defs/time" },
-        "run_signer_time_zone": { "type": ["string", "null"] }
+        "run_signer_time_zone": { "type": ["string", "null"] },
+        "session": { "type": ["string", "null"], "description": "Key of the role that performs the step (the step's session:)." },
+        "session_title": { "type": ["string", "null"] },
+        "lane": { "type": ["integer", "null"], "description": "The step's lane (sub-process), from 0." },
+        "lane_label": { "type": ["string", "null"] }
       }
     },
     "release": {
@@ -231,6 +253,7 @@
         "release": { "type": "object", "description": "{ product, version, released_on, tag, commit, runs: [run id] }." },
         "runs": { "type": "array", "items": { "$ref": "#/$defs/run" }, "description": "The evidence of each run of the release the caller can read." },
         "missing": { "type": "array", "items": { "type": "object", "properties": { "run": { "type": "string" }, "reason": { "type": "string" } } }, "description": "Runs of the release without evidence here, with the reason." },
+        "filter": { "type": "object", "properties": { "ref": { "type": "string" }, "purpose": { "type": "string" } }, "description": "Present when the request narrowed the release to the runs of one record (?ref=) or purpose (?purpose=); runs then holds only those; missing still lists the runs that could not be read, since their references are unknown here." },
         "trace": { "type": "array", "items": { "$ref": "#/$defs/traceRow" } }
       }
     },

package/schemas/run.v1.json

@@ -332,6 +332,25 @@
         }
       }
     },
+    "refs": {
+      "type": "array",
+      "maxItems": 20,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/#+-]{0,79}$"
+      },
+      "description": "External records the run serves, e.g. a change-control record (kaloko start --ref, KALOKO_REFS). The service filters runs by them (GET …/runs?ref=)."
+    },
+    "purpose": {
+      "enum": [
+        "dry_run",
+        "formal",
+        "smoke",
+        null
+      ],
+      "description": "Why the run was walked (kaloko start --purpose, KALOKO_PURPOSE): a dry run, a formal run or a smoke run. A label; it changes nothing about how the run is walked or decided."
+    },
     "sessions": {
       "type": [
         "object",

package/skills/kaloko/SKILL.md

@@ -210,9 +210,12 @@ only when a person says that value may be uploaded.
   tools (relative URLs, no CDNs, state in the URL, deterministic content,
   links between steps; what `kaloko design lint` checks):
   [reference/portable-html.md](reference/portable-html.md)
-- Command reference: `kaloko help`; when something does not work (Chrome,
+- Command reference: `kaloko help` (`kaloko help --json` lists every command,
+  sub-command and option as data); when something does not work (Chrome,
   token, environment URL, evaluator key), run `kaloko doctor` first and fix
-  what it marks ✕.
+  what it marks ✕. When a command answers "… is in kaloko X (you have Y)",
+  the project's kaloko is too old for it: tell the person and suggest the
+  update command from that line; change the dependency only when they agree.
 
 Project configuration is `kaloko.config.yml` in the repository root.
 Project skills may add conventions (paths, test data, locales); follow them

package/skills/kaloko/reference/collaboration.md

@@ -134,6 +134,12 @@ choice of branch at every decision node. `#replay=1&step=<id>&path=a,b,c`
 deep-links a specific path, so an issue comment can point at "the sign-in
 branch, step 3". Replay reads the manifest only; nothing is uploaded.
 
+A link can also open the map on one part of the flow: `#lane=<index>` fits
+and highlights that lane (lanes count from 0, in the order of the scenario's
+`lanes:`, or of its `sessions:` when it has no lanes), and `#session=<key>`
+highlights one person's steps across all lanes. `get_run_summary` lists the
+run's `lanes` and `sessions`, and every step names its `lane` and `session`.
+
 For people who work through a list rather than a flow (QA leads, content
 and SEO teams, big runs), switch the canvas to **Index**. Use *Map | Index*
 in the top bar, the key `I`, or `#mode=index` in the URL.
@@ -277,7 +283,7 @@ Everything above is available over the API with an organization token:
   `…/signoff.html`: the signed acceptance record of an accepted run.
 - `GET /api/v1/orgs/<org>/notifications[?unread=1]`, `POST` with
   `{"read": "all"}` or `{"read": [ids]}`
-- `GET /api/v1/orgs/<org>/runs[?project=&scenario=&kind=&verdict=&author=&environment=&branch=&q=][&latest=1]`
+- `GET /api/v1/orgs/<org>/runs[?project=&scenario=&kind=&verdict=&author=&environment=&branch=&ref=&purpose=&q=][&latest=1]`
   (`latest=1`: the newest run per scenario with `older`), `GET /api/v1/orgs/<org>/runs/<id>`
 - Paging: runs, `comments`, `notifications`, `tokens` and `audit` take
   `?limit=` and `?cursor=`. The body keeps its shape (an array stays an

package/skills/kaloko/reference/evidence.md

@@ -21,8 +21,12 @@ described). Within v1 fields are only added; read the fields you need and ignore
   is signed elsewhere; your document says so ("executed in Kaloko; approval recorded in <your eQMS>").
 - `record.sha256` and `record.kind` (`acceptance` or `execution`): the signed record the evidence came from. Put the
   hash into your document so a reader can tie it to the package.
-- `scenario` (`version`, `file`, `sha256`, `refs`), `environment`, `git`, `tools` (CLI, Node.js, OS, browsers,
-  service version).
+- `scenario` (`version`, `file`, `sha256`, `refs`, `lanes`, `sessions`), `environment`, `git`, `tools` (CLI,
+  Node.js, OS, browsers, service version). `scenario.lanes` lists the flow's lanes (`{ index, label }`, the
+  sub-processes) and `scenario.sessions` its roles (`{ key, title }`); without `lanes:` in the scenario, each session
+  is a lane.
+- `steps[].session` (`{ key, title }`, the role that performs the step, or null) and `steps[].lane`
+  (`{ index, label }`; `label` is null for an unnamed lane).
 - `steps[].criteria[]`: the criterion text as walked, `refs`, and `results[]` per locale and viewport with
   `assessed_by` (`person`, `deterministic`, `ai`, `none`) and `assessor` (an e-mail or a model id). `advisory: true`
   means an AI result no person decided: never present it as a person's verdict.
@@ -31,7 +35,8 @@ described). Within v1 fields are only added; read the fields you need and ignore
 - `signatures[]` (name, e-mail, `signed_at`, `time_zone`, `local_time`, `meaning`, `auth`, `withdrawn`) and
   `decision_changes[]` with reasons.
 - `audit[]`: the run's audit trail; `trace[]`: the trace matrix, one row per requirement, criterion, step, locale and
-  viewport (columns in `TRACE_COLUMNS` order, the same as `trace.csv`).
+  viewport (columns in `TRACE_COLUMNS` order, the same as `trace.csv`). Each row names the step's role and lane in
+  `session`, `session_title`, `lane` and `lane_label` (the last four columns of the CSV).
 - A release (`kind: release`) has `runs[]` (each a run evidence), `missing[]` with reasons and one `trace[]`.
 
 ## Getting it
@@ -48,6 +53,42 @@ Over the API with a read token: `GET /api/v1/orgs/<org>/runs/<id>/evidence`, `
 `…/audit.csv`, and `GET /api/v1/orgs/<org>/evidence?product=<p>&version=<v>`. Over MCP: `get_evidence` with `run_id`, or
 `product` and `version`.
 
+## A screen next to the test step
+
+A documentation portal that shows a step's screenshot beside the test step fetches it with a read token limited to
+the project (send it as `Authorization: Bearer …` from the portal's server; never put the token in a page):
+
+```
+GET /api/v1/orgs/<org>/runs/<run>/steps/<step>/screen?locale=en&viewport=desktop&size=thumb&sha256=<hex>
+```
+
+- `locale` and `viewport` default to the run's first ones that the step has. A value the run does not have, a value
+  given twice, or `size` other than `thumb` or `full` answers 400. A screenshot the step does not have answers 404.
+  Errors after the run check carry `canvas`, the link to the step.
+- The answer is the image with `ETag` (the SHA-256 of the file served) and `X-Kaloko-SHA256` (the SHA-256 of the
+  step's screenshot, the one `steps[].captures[].sha256` and the trace matrix list, for `thumb` too). `If-None-Match`
+  answers 304. `X-Kaloko-Locale`, `X-Kaloko-Viewport` and `X-Kaloko-Size` say what was served; a capture without a
+  thumbnail answers the full screenshot with `X-Kaloko-Size: full`. `Link` holds the step on the canvas.
+- Store run, step, locale, viewport and that SHA-256, and send it back as `sha256`. When the run holds a different
+  file the answer is 409 with the run's `sha256`, so the portal never shows a picture nobody checked.
+- Access is the run's: guests and project-limited tokens get 404 outside their projects, and nothing is served without
+  a token or a session (public links included). The image cannot be framed by other sites; link the reader to the
+  step on the canvas, where they sign in with their own account.
+
+Over MCP: `get_step_screen` with `run_id`, `step` and optionally `locale`, `viewport`, `size`, `sha256` answers the
+hashes, the canvas link and a `url` pinned to that file (no image bytes).
+
+## Runs of an external record
+
+When the run serves a record in the client's QMS (a change request, a validation protocol), start it with
+`--ref CC-2026-001` (repeatable; `KALOKO_REFS` in CI, comma or space separated) and, when known,
+`--purpose dry_run|formal|smoke` (`KALOKO_PURPOSE`). Up to 20 references of up to 80 characters: letters, digits and
+`. _ - / : # +`. They are stored in the run (`refs`, `purpose` next to `issue`), shown in the canvas header, and the
+evidence carries them as `run.refs` and `run.purpose`. Find the runs of a record with
+`GET /api/v1/orgs/<org>/runs?ref=CC-2026-001[&purpose=formal]`, `kaloko runs --ref CC-2026-001` or MCP `list_runs`
+with `ref`; the release evidence takes `&ref=` and `&purpose=` too (`kaloko evidence --release <v> --ref …`). Never
+invent a reference: ask which record the run is for, or leave it out.
+
 ## When it is ready
 
 An organization admin adds a webhook with the event `evidence.ready` (Settings → Integrations → Webhooks). It fires

package/skills/kaloko/reference/execution.md

@@ -24,6 +24,11 @@ call `kaloko session reset` themselves when the plan starts as a new visitor.
 `start` prints a unique test e-mail address for the run; use it in forms so
 `mail` can find the message.
 
+`start --ref CC-2026-001 [--ref …] [--purpose dry_run|formal|smoke]` links the
+run to records outside Kaloko (a change request, a protocol) and says why it
+was walked; `KALOKO_REFS` and `KALOKO_PURPOSE` do the same in CI. See
+`evidence.md` → Runs of an external record.
+
 ## Choosing a strategy per step
 
 - `playwright` — stable, repeatable steps. The script exports

package/skills/kaloko/reference/mcp.md

@@ -27,12 +27,13 @@ is null. Projects and products come complete, without pages.
 
 | Tool | Use it for |
 |---|---|
-| `list_runs` | published runs, newest first; filters `scenario`, `project`, `verdict`, `author`, `environment`, `branch`, `limit`; `cursor` for the next page |
+| `list_runs` | published runs, newest first; filters `scenario`, `project`, `verdict`, `author`, `environment`, `branch`, `ref` (a record the run serves), `purpose` (`dry_run`, `formal`, `smoke`), `limit`; `cursor` for the next page |
 | `get_run_summary` | one run: statuses per step and locale, criteria that need attention with evidence (semantic ones with score and the evaluator's one-sentence `reason` per locale and viewport), regions ignored in pixel diffs and regions seen moving (`ignored_regions`, `unstable_regions`), screenshot URLs, verdict, baseline, canvas URL, open feedback |
 | `get_feedback` | run verdict with note, approved steps, unresolved rejections and comments, failed manual criteria (`run_id`, or `scenario` for its latest run) |
 | `list_notifications` | the token owner's inbox (`unread_only`, `limit`, `cursor`) |
 | `list_projects` | projects of the organization with counts; the slug is the `project` filter of `list_runs` and the value for `project:` in a scenario |
 | `upsert_project` | creates a project (`slug`, `name`, `visibility`, `product`; `create: true` refuses an existing one) or renames it; the same rules as `kaloko projects create\|rename\|sync` (a full token; renaming is for the project's admin). Ask before renaming |
+| `get_step_screen` | one step's screenshot of a run, pinned (`run_id`, `step`, `locale`, `viewport`, `size` thumb or full, `sha256`): the SHA-256 of the screenshot and of the file, a `url` that fetches exactly that file with the same token, the canvas link; see [evidence.md](evidence.md) |
 | `get_criteria_verdicts` | reviewer verdicts on manual or overridden criteria of a run |
 | `get_stack_items` | the pages of a stack step (`run_id`, `step`; filters `status`, `criterion`, text): path, URL, title, status and failing criteria with evidence, screenshot URLs |
 | `get_step_recording` | a step's recording and trace (`run_id`, `step`, `locale`, `viewport`, `trace: true` for the full trace): video URLs, duration, its chapter of a flow recording, failed attempts, the trace summary (failed requests, console errors, slowest request); see [recording.md](recording.md). `get_run_summary` lists trace summaries per step too |

package/src/cli.mjs

@@ -8,6 +8,7 @@ import yaml from 'js-yaml'
 import { loadConfig, environment, urlFor, baseUrl, CONFIG_FILE, LEGACY_CONFIG_FILE } from './lib/config.mjs'
 import { loadScenario, parseScenario, validateScenario, scenarioWarnings } from './lib/scenario.mjs'
 import { createRun, resolveRun, readCaptures, listRuns } from './lib/run.mjs'
+import { startRefs, normalizePurpose, RUN_PURPOSES } from './lib/run-refs.mjs'
 import { gitMeta, projectAndIssue, appVersion } from './lib/git.mjs'
 import { startBrowser, stopBrowser, connectBrowser, currentPage, launchEphemeral, launchWithRetry, consoleLog, allStates, resetSession, acquireWalkLock } from './lib/browser.mjs'
 import { captureStep, captureCrop, captureOptions, acceptDialogs } from './lib/capture.mjs'
@@ -39,7 +40,7 @@ import { formatReviewQueue, shareReviewLine } from './lib/review.mjs'
 import { healthCmd } from './lib/health.mjs'
 import { htmlViewAllowed } from './lib/htmlview.mjs'
 import { service, serviceUrl } from './lib/service.mjs'
-import { parseArgs, helpFor, checkOptions, closest } from './lib/cli-args.mjs'
+import { parseArgs, helpFor, checkOptions, closest, catalogue, unknownOptions, subcommandsFor, takesWords } from './lib/cli-args.mjs'
 import { issueCmd, scheduleCmd } from './lib/integrations-cli.mjs'
 import { login } from './lib/login.mjs'
 import { initNextSteps, loginNextSteps } from './lib/onboarding.mjs'
@@ -67,6 +68,7 @@ import { startScope, scopeKeys, dimensionLine, baseViewports, engineKeys, appDev
 import { deviceConfig, prepareAndroid, readyAndroid, finishAndroid, prepareSimulator, applyAppAppearance } from './lib/apps/devices.mjs'
 import { attachAndroidWebView } from './lib/apps/webview.mjs'
 import { piiSettings, piiFindings, piiRequested, guardAllow, formatFindings } from './lib/pii.mjs'
+import { updateHint } from './lib/update-check.mjs'
 
 
 /** Options every command takes and the exit codes; the end of kaloko help and of the help of each command. */
@@ -78,9 +80,10 @@ const COMMON_HELP = `Common options (every command)
                                     JSON, progress and notes go to stderr, and an error is one line on stderr:
                                     {"error":{"message":"…","code":"…","next":"…"}} with the exit code below
   --help, -h                        Help for one command, like kaloko help <command> (kaloko help export run: one
-                                    sub-command)
+                                    sub-command); kaloko help --json lists every command, sub-command and option
   --version, -v                     The version of kaloko (also kaloko version)
   KALOKO_AGENT=<name>               Labels writes by an agent
+  KALOKO_NO_UPDATE_CHECK=1          An unknown command or option does not ask kaloko.app whether a newer kaloko has it
   Durations (--timeout, --wait, --expires, --older-than) take a number in the option's unit or one with s, m, h or d:
   90s, 10m, 2h, 14d
 
@@ -141,6 +144,9 @@ Run
   start --scenario <file> --env <name> [--locales cs,en] [--viewports desktop,mobile] [--executor <name>]
                                     [--app-version <v>] (default: the git tag on HEAD; documentation captures carry it)
                                     Create a run directory and make it current (--json: the run id and its folder)
+       [--ref CC-2026-001] [--ref …]   Records the run serves (change control, protocol); repeat it or separate
+                                    with commas; KALOKO_REFS in CI. kaloko runs --ref lists the runs of a record
+       [--purpose dry_run|formal|smoke]   Why the run was walked, shown as a label; KALOKO_PURPOSE in CI
        [--viewports iphone-15,ipad-landscape,desktop]   Viewport names of the scenario or device presets
                                     (kaloko devices lists them; <preset>-landscape turns one sideways)
        [--browsers chromium,webkit,firefox] [--color-schemes light,dark] [--reduced-motion no-preference,reduce]
@@ -267,10 +273,11 @@ Results
   projects sync [--json]            Make Kaloko match project:, project_name: and product: of the config: create
                                     the project when it is missing, rename it when the name differs, add it to the
                                     product. A share never renames a project; it says when the names differ
-  runs [--scenario id] [--env e] [--all] [--limit N] [--cursor c] [--json]
+  runs [--scenario id] [--env e] [--ref r] [--purpose p] [--all] [--limit N] [--cursor c] [--json]
                                     Shared runs: the newest per scenario (with "+ N older"); --all or --scenario lists every
                                     run: --all to the last one page by page, otherwise the newest 300; --limit N lists at
-                                    most N, --cursor c goes on where a list stopped (it prints the cursor)
+                                    most N, --cursor c goes on where a list stopped (it prints the cursor); --ref r lists
+                                    every run of a record, --purpose p only dry runs, formal runs or smoke runs
   trash <run-id>... | restore <run-id>
                                     Move runs to the trash (uploader or admin) and back; restorable until purge
   prune [--scenario id] [--env e] [--keep 3] [--older-than 14d|48h] [--dry-run | --yes] [--json]
@@ -310,7 +317,7 @@ Results
                                     Check a record or an evidence package someone handed over (no token needed); exit 1
                                     when it does not verify
   evidence <run-id> [--csv] [--out file] [--json]
-  evidence --release <version> [--product p] [--csv] [--out file] [--json]
+  evidence --release <version> [--product p] [--ref r] [--purpose p] [--csv] [--out file] [--json]
                                     The evidence of a run or a release (Business, schema qawalk.evidence.v1): acceptance
                                     and signing state, criteria as walked with requirement refs, results, screenshots
                                     with SHA-256, decisions, signatures, audit trail; --csv prints the trace matrix
@@ -1255,6 +1262,9 @@ const commands = {
   async start (args) {
     const { config, root } = await context(args)
     if (!args.scenario || !args.env) throw new UsageError('Usage: kaloko start --scenario <file> --env <name>')
+    // the records the run serves and why it was walked (#126): checked before anything is created
+    const { refs, purpose, problems: refIssues } = startRefs(args, process.env)
+    if (refIssues.length) throw new UserError(refIssues.join('\n'))
     const scenarioFile = resolve(args.scenario)
     const scenario = await loadScenario(scenarioFile)
     const env = environment(config, args.env)
@@ -1274,11 +1284,12 @@ const commands = {
     const appVer = typeof args['app-version'] === 'string' ? args['app-version'].slice(0, 80) : await appVersion(root)
     // the product the flow documents (visual changelog): its tag, or the only product of the config
     const product = scenario.product || (Object.keys(config.products || {}).length === 1 ? Object.keys(config.products)[0] : null)
-    const { dir, meta } = await createRun({ output: config.output, scenario, scenarioFile, env, scope, git, executor, root, project, issue, appVersion: appVer, product, pii })
+    const { dir, meta } = await createRun({ output: config.output, scenario, scenarioFile, env, scope, git, executor, root, project, issue, refs, purpose, appVersion: appVer, product, pii })
     const addr = recipient(env.mail, meta.short)
     // --json: what a script needs to pin the run (KALOKO_RUN) and find its files
-    if (args.json) { say(JSON.stringify({ run: meta.id, dir, env: env.name, readonly: !!env.readonly, locales, viewports: vpNames, project: project.slug, issue: issue || null, test_email: addr || null, pii: pii?.mode || null }, null, 2)); return }
+    if (args.json) { say(JSON.stringify({ run: meta.id, dir, env: env.name, readonly: !!env.readonly, locales, viewports: vpNames, project: project.slug, issue: issue || null, refs, purpose, test_email: addr || null, pii: pii?.mode || null }, null, 2)); return }
     say(`Run ${meta.id}\n  dir: ${relative(process.cwd(), dir)}\n  env: ${env.name}${env.readonly ? ' (readonly)' : ''}\n  locales: ${locales.join(', ')}  viewports: ${vpNames.length > 12 ? `${vpNames.slice(0, 12).join(', ')} … (${vpNames.length})` : vpNames.join(', ')}${dimensionLine(scope)}\n  project: ${project.slug}${issue ? `  issue: ${issue.repo ? issue.repo + '#' : '#'}${issue.number}` : ''}`)
+    if (refs.length || purpose) say(`  ${[refs.length && `refs: ${refs.join(', ')}`, purpose && `purpose: ${purpose}`].filter(Boolean).join('  ')}`)
     if (pii) say(`  personal data: ${pii.mode === 'pseudonymize' ? 'replaced with fake values' : 'hidden'} in every capture`)
     if (addr) say(`  test e-mail: ${addr}`)
     say(`  other agents may start runs here too: pin this one with --run ${meta.id} or KALOKO_RUN=${meta.id}`)
@@ -2328,7 +2339,11 @@ const commands = {
   async runs (args) {
     const { config } = await context(args)
     const client = service(config)
-    const all = !!args.all || typeof args.scenario === 'string'
+    // --ref: every run of a record (#126), not only the newest per scenario
+    const ref = typeof args.ref === 'string' ? args.ref : null
+    const purpose = args.purpose === undefined ? null : normalizePurpose(args.purpose === true ? '' : args.purpose)
+    if (args.purpose !== undefined && !purpose) throw new UsageError(`--purpose takes one of ${RUN_PURPOSES.join(', ')}.`)
+    const all = !!args.all || typeof args.scenario === 'string' || !!ref
     const envName = envOption(args)
     // --limit N: at most N runs; --all follows the service's cursors to the last run, otherwise the newest RUNS_CAP;
     // --cursor continues where an earlier list stopped (the cursor it printed)
@@ -2339,18 +2354,18 @@ const commands = {
     let next = null
     do {
       const page = Math.min(1000, want - runs.length)
-      const q = new URLSearchParams({ ...(all ? {} : { latest: '1' }), ...(typeof args.scenario === 'string' ? { scenario: args.scenario } : {}), ...(envName ? { environment: envName } : {}), limit: String(page), ...(cursor ? { cursor } : {}) })
+      const q = new URLSearchParams({ ...(all ? {} : { latest: '1' }), ...(typeof args.scenario === 'string' ? { scenario: args.scenario } : {}), ...(envName ? { environment: envName } : {}), ...(ref ? { ref } : {}), ...(purpose ? { purpose } : {}), limit: String(page), ...(cursor ? { cursor } : {}) })
       const got = await client.page(`/orgs/${config.org}/runs?${q}`)
       runs.push(...got.data)
       next = cursor = got.next
     } while (next && runs.length < want)
     // more runs than were listed: say how to go on (on stderr, so --json stays one JSON array)
-    if (next) console.error(`Showing ${runs.length}; there are more. kaloko runs${args.all ? ' --all' : ''}${typeof args.scenario === 'string' ? ` --scenario ${args.scenario}` : ''}${envName ? ` --env ${envName}` : ''} --cursor ${next} lists the next ones${all && !args.all ? ', --all every one' : ''}.`)
+    if (next) console.error(`Showing ${runs.length}; there are more. kaloko runs${args.all ? ' --all' : ''}${typeof args.scenario === 'string' ? ` --scenario ${args.scenario}` : ''}${envName ? ` --env ${envName}` : ''}${ref ? ` --ref ${ref}` : ''}${purpose ? ` --purpose ${purpose}` : ''} --cursor ${next} lists the next ones${all && !args.all ? ', --all every one' : ''}.`)
     if (args.json) { say(JSON.stringify(runs, null, 2)); return }
     if (!runs.length) { say('No shared runs match.'); return }
     for (const r of runs) {
       const s = r.summary || {}
-      say(`${r.id}  ${r.environment?.name || ''}  ${r.verdict || 'pending'}${r.kept ? ' · kept' : ''}  ${s.pass || 0}✓ ${s.partial || 0}◐ ${s.fail || 0}✕  ${r.author || ''}${r.older ? `  + ${r.older} older` : ''}`)
+      say(`${r.id}  ${r.environment?.name || ''}${r.purpose ? ` (${r.purpose})` : ''}  ${r.verdict || 'pending'}${r.kept ? ' · kept' : ''}  ${s.pass || 0}✓ ${s.partial || 0}◐ ${s.fail || 0}✕  ${r.author || ''}${r.older ? `  + ${r.older} older` : ''}`)
     }
     if (!all) say(`\nNewest run per scenario; --all or --scenario <id> lists every run.`)
   },
@@ -2722,11 +2737,18 @@ const commands = {
   /** `kaloko help [command]`: everything, or the entries of one command with the common options. */
   async help (args = { _: [] }) {
     const topic = args._?.[0]
+    // kaloko help --json: every command, sub-command and option as data (kaloko help prune --json: that command)
+    if (args.json) {
+      const all = await cliCatalogue()
+      if (!topic) { say(JSON.stringify(all, null, 2)); return }
+      if (all.commands[topic]) { say(JSON.stringify({ version: all.version, commands: { [topic]: all.commands[topic] } }, null, 2)); return }
+      return unknownCommand(topic, true, args)
+    }
     if (!topic) { say(HELP); return }
     // kaloko help export run: the entries of that sub-command (all of the command's when it has none by that name)
     const text = commands[topic] && topic !== 'help' ? helpFor(HELP, topic, COMMON_HELP, args._?.[1]) : null
     if (text) { say(text); return }
-    unknownCommand(topic)
+    return unknownCommand(topic, false, args)
   }
 }
 
@@ -2735,14 +2757,41 @@ async function packageVersion () {
   return JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8')).version
 }
 
-/** "There is no command": the nearest command when it looks like a typo, the full help, exit code 2. */
-function unknownCommand (name, json = false) {
-  const guess = closest(name, Object.keys(commands))
-  const message = `There is no command "${name}".${guess ? ` Did you mean kaloko ${guess}?` : ''}`
-  if (json) { console.error(JSON.stringify(jsonError(new UsageError(message, { next: 'kaloko help lists the commands.' })))); process.exitCode = EXIT.usage; return }
+/** Every command, sub-command and option of this kaloko as data: kaloko help --json, and the service's /cli/latest.json. */
+export async function cliCatalogue () {
+  return catalogue(HELP, [...Object.keys(commands), 'version'], await packageVersion())
+}
+
+/**
+ * "There is no command": when a newer kaloko has it, the line that says which version and how to update; else the
+ * nearest command when it looks like a typo and the full help. Exit code 2 either way.
+ */
+async function unknownCommand (name, json = false, args = {}) {
+  process.exitCode = EXIT.usage
+  const update = await newerKaloko({ command: name }, args)
+  const guess = update ? null : closest(name, Object.keys(commands))
+  const message = `There is no command "${name}"${update ? ' in this kaloko' : ''}.${guess ? ` Did you mean kaloko ${guess}?` : ''}`
+  if (json) { console.error(JSON.stringify(jsonError(new UsageError(message, { next: update || 'kaloko help lists the commands.' })))); return }
+  if (update) { console.error(`${message}\n${update}`); return }
   console.error(`${message} The commands are below; kaloko help <command> explains one.\n`)
   say(HELP)
-  process.exitCode = EXIT.usage
+}
+
+/** A usage error whose next step is updating kaloko (printed on its own line). */
+const updateError = (reason, update) => Object.assign(new UsageError(reason, { next: update }), { update: true })
+
+/**
+ * The update line for what this kaloko does not know ({ command, sub, options }), or null: only when the newest
+ * released kaloko (the service's /cli/latest.json, cached for a day) is newer and has exactly that. With `detail`:
+ * { update: line, newer: [options the newer kaloko takes] }.
+ */
+async function newerKaloko (typed, args = {}, detail = false) {
+  try {
+    let config = {}
+    try { ({ config } = await loadConfig(process.cwd(), typeof args.config === 'string' ? args.config : undefined)) } catch {}
+    const r = await updateHint(typed, { installed: await packageVersion(), config, root: packageRoot, args })
+    return detail ? r : r?.line || null
+  } catch { return null }
 }
 
 /** A line of output that is a JSON document (the --json answer), told apart from progress and notes. */
@@ -2782,13 +2831,27 @@ async function runCommand (args, json) {
   if ((!args._.length && args.version) || args._[0] === 'version') { say(json ? JSON.stringify({ version: await packageVersion() }) : await packageVersion()); return }
   const name = args._.shift() || 'help'
   const cmd = commands[name]
-  if (!cmd) { if (args.help) say(HELP); else unknownCommand(name, json); return }
+  if (!cmd) { if (args.help) say(HELP); else await unknownCommand(name, json, args); return }
   // kaloko <command> --help: the command's help instead of running it
   if (args.help && name !== 'help') { say(helpFor(HELP, name, COMMON_HELP, args._[0]) || HELP); return }
+  // what this kaloko does not know: a word after a command that takes none (kaloko projects create) and options its
+  // help does not name. A newer kaloko may have them; only then a line says which version and how to update.
+  const word = name !== 'help' && typeof args._[0] === 'string' && !subcommandsFor(HELP, name).has(args._[0]) ? args._[0] : null
+  const unknown = unknownOptions(HELP, name, args)
   try {
-    for (const line of checkOptions(HELP, name, args)) console.error(line)
+    if (word && !takesWords(HELP, name)) {
+      const update = await newerKaloko({ command: name, sub: word }, args)
+      if (update) throw updateError(`There is no "kaloko ${name} ${word}" in this kaloko.`, update)
+    }
+    const newer = unknown.length ? await newerKaloko({ command: name, options: unknown }, args, true) : null
+    for (const line of checkOptions(HELP, name, args, newer || {})) console.error(line)
     await cmd(args)
   } catch (error) {
+    // a usage error over a sub-command a newer kaloko has (kaloko tokens <new>): say so instead of only the help
+    if (error instanceof UsageError && !error.update && !error.next && word) {
+      const update = await newerKaloko({ command: name, sub: word }, args)
+      if (update) error = updateError(error.reason, update)
+    }
     const known = error instanceof UserError
     if (json) {
       // the reason in one JSON line on stderr, the documented exit code; a bug also prints its stack before it
@@ -2798,7 +2861,7 @@ async function runCommand (args, json) {
       return
     }
     // a usage mistake: the command's help says what is wrong; no support line, exit code 2
-    if (error instanceof UsageError) { console.error(`${error.message}${/kaloko help /.test(error.message) ? '' : `\nkaloko help ${name} shows how to use it.`}`); process.exitCode = EXIT.usage } else if (known) { console.error(`${error.message}\n${SUPPORT_LINE}`); process.exitCode = exitCodeOf(error) } else {
+    if (error instanceof UsageError && error.update) { console.error(`${error.reason}\n${error.next}`); process.exitCode = EXIT.usage } else if (error instanceof UsageError) { console.error(`${error.message}${/kaloko help /.test(error.message) ? '' : `\nkaloko help ${name} shows how to use it.`}`); process.exitCode = EXIT.usage } else if (known) { console.error(`${error.message}\n${SUPPORT_LINE}`); process.exitCode = exitCodeOf(error) } else {
       console.error(`Kaloko stopped on an unexpected error (a bug on our side). Send the output below to ${SUPPORT_EMAIL} with the command you ran.`)
       throw error
     }

package/src/lib/build.mjs

@@ -69,6 +69,8 @@ export async function buildManifest ({ run, scenario, config, root, catalog = []
     git: meta.git,
     project: meta.project || null,
     issue: meta.issue || null,
+    ...(meta.refs?.length ? { refs: meta.refs } : {}),
+    ...(meta.purpose ? { purpose: meta.purpose } : {}),
     // version of the application under test; `version` is the number of a design version (#42)
     app_version: meta.app_version ?? meta.version ?? null,
     environment: meta.environment,