kaloko 0.16.1 → 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.1",
+  "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",

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/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'
@@ -143,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]
@@ -269,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]
@@ -312,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
@@ -1257,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)
@@ -1276,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}`)
@@ -2330,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)
@@ -2341,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.`)
   },

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,

package/src/lib/cli-args.mjs

@@ -50,13 +50,21 @@ export const HIDDEN = {
  */
 export const STRICT = new Set(['prune', 'trash', 'restore', 'keep', 'archive', 'public', 'release', 'comment', 'projects create', 'projects rename', 'projects sync'])
 
+/**
+ * Options a command takes more than once (kaloko start --ref A --ref B): their value is the list of every value given.
+ * Elsewhere the same name keeps the last value (kaloko spec --ref design).
+ */
+export const REPEATABLE = { start: ['ref'] }
+
 /**
  * argv → { _: positional, <option>: value | true }. `--key=value` splits at the first `=` only; `--key value` takes
- * the next word unless it is another option; `-h` and `-v` are --help and --version.
+ * the next word unless it is another option; `-h` and `-v` are --help and --version. An option REPEATABLE for the
+ * command (the first positional) collects its values in a list.
  */
 export function parseArgs (argv) {
   const args = { _: [] }
   const short = { '-h': 'help', '-v': 'version' }
+  const seen = {}
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a.startsWith('--')) {
@@ -66,9 +74,11 @@ export function parseArgs (argv) {
       if (eq >= 0) args[k] = a.slice(eq + 1)
       else if (next && !next.startsWith('--') && !short[next]) args[k] = argv[++i]
       else args[k] = true
+      ;(seen[k] ||= []).push(args[k])
     } else if (short[a]) args[short[a]] = true
     else args._.push(a)
   }
+  for (const k of REPEATABLE[args._[0]] || []) if (seen[k]) args[k] = seen[k]
   return args
 }
 

package/src/lib/docs-core.mjs

@@ -419,12 +419,14 @@ function blocks (lines, o) {
 
 /** A list item: its first paragraph inline (tight lists), the rest as blocks (nested lists, pictures, code). */
 function listItem (lines, o) {
+  // lists nest at most 16 deep, like quotes; deeper items are text (1 000 levels of "- - -" would overflow the stack)
+  if ((o.listDepth || 0) >= 16) return inlineHtml(lines.join(' ').trim(), o)
   const first = []
   let i = 0
   while (i < lines.length && lines[i].trim() && !LIST.test(lines[i]) && !/^\s{0,3}(```|~~~)/.test(lines[i])) first.push(lines[i++])
   const { imgs, words } = picturesOf(first.join('\n'))
   const rest = lines.slice(i)
-  return `${words ? inlineHtml(words.replace(/\n/g, ' '), o) : ''}${imgs.length ? pics(imgs, o) : ''}${rest.some((l) => l.trim()) ? blocks(rest, { ...o, notice: null }) : ''}`
+  return `${words ? inlineHtml(words.replace(/\n/g, ' '), o) : ''}${imgs.length ? pics(imgs, o) : ''}${rest.some((l) => l.trim()) ? blocks(rest, { ...o, notice: null, listDepth: (o.listDepth || 0) + 1 }) : ''}`
 }
 
 function pics (imgs, o) {

package/src/lib/evidence-core.mjs

@@ -6,12 +6,14 @@
 //   evidenceOf(record, extras)   the evidence document of one run, derived from its signed acceptance record
 //   releaseEvidenceOf(...)       the evidence document of a release: its runs and one trace matrix over all of them
 //   traceRows(evidence)          the trace matrix: requirement → criterion → step/locale/viewport → evidence → result
-//                                → human decision; TRACE_COLUMNS is the column order of the CSV
+//                                → human decision, with the step's session (role) and lane; TRACE_COLUMNS is the
+//                                column order of the CSV
 //   signatureSubject(...)        what an electronic signature is bound to; verifySignatures(record) recomputes it
 //   packageManifest / verifyPackageFiles   the MANIFEST.json of an evidence package and its check
 //
 // The JSON is the contract; CSV is a convenience for people (cells that start like a formula get a leading ').
 import { canonicalJson, sha256Hex, recordSha256, verifyRecord } from './signoff-core.mjs'
+import { stepPlaces, flowStructure } from './lanes-core.mjs'
 
 export const EVIDENCE_SCHEMA = 'qawalk.evidence.v1'
 export const MANIFEST_FILE = 'MANIFEST.json'
@@ -26,7 +28,9 @@ export const TRACE_COLUMNS = [
   'criterion_id', 'criterion_text', 'criterion_type', 'locale', 'viewport', 'evidence_file', 'evidence_sha256',
   'result', 'assessed_by', 'assessor', 'advisory',
   'step_decision', 'step_decided_by', 'step_decided_at', 'step_decided_via', 'step_signature_meaning', 'step_signer_name', 'step_signed_at', 'step_signer_time_zone', 'step_comment',
-  'run_verdict', 'run_decided_by', 'run_decided_at', 'run_decided_via', 'run_signature_meaning', 'run_signer_name', 'run_signed_at', 'run_signer_time_zone'
+  'run_verdict', 'run_decided_by', 'run_decided_at', 'run_decided_via', 'run_signature_meaning', 'run_signer_name', 'run_signed_at', 'run_signer_time_zone',
+  // added later, so they come last: a reader that takes columns by position keeps working
+  'session', 'session_title', 'lane', 'lane_label'
 ]
 export const AUDIT_COLUMNS = ['at', 'actor', 'action', 'target', 'via', 'agent', 'country', 'source', 'detail']
 
@@ -87,11 +91,15 @@ const sigCols = (s, prefix) => ({ [`${prefix}_signature_meaning`]: s?.meaning ??
 /**
  * The evidence document of a run (qawalk.evidence.v1, kind run) from its acceptance record. extras: { record_sha256,
  * signed (the record carries the service's signature), audit (rows of the run's audit trail), generated_at,
- * public_keys (URL of the well-known keys) }.
+ * public_keys (URL of the well-known keys), manifest (the run's run.json: the record names its SHA-256; it gives each
+ * step its session and lane, and the scenario its lanes and sessions) }.
  */
-export function evidenceOf (record, { record_sha256: recordSha = null, signed = !!record?.signature, audit = [], generated_at: at = new Date().toISOString(), public_keys: keysUrl = null } = {}) {
+export function evidenceOf (record, { record_sha256: recordSha = null, signed = !!record?.signature, audit = [], generated_at: at = new Date().toISOString(), public_keys: keysUrl = null, manifest = null } = {}) {
   const r = record || {}
   const run = r.run || {}
+  const places = manifest ? stepPlaces(manifest) : null
+  const flow = manifest ? flowStructure(manifest) : null
+  const placed = (s) => ({ session: places?.get(s.id)?.session ?? s.session ?? null, lane: places?.get(s.id)?.lane ?? s.lane ?? null })
   const ev = {
     schema: EVIDENCE_SCHEMA,
     kind: 'run',
@@ -102,8 +110,8 @@ export function evidenceOf (record, { record_sha256: recordSha = null, signed =
     acceptance: r.acceptance ?? (r.verdict?.verdict === 'accepted' ? 'accepted' : r.verdict?.verdict === 'returned' ? 'returned' : 'none'),
     signing: r.signing ?? ((r.signatures || []).some((x) => !x.withdrawn) ? 'in_kaloko' : 'none'),
     record: { schema: r.schema ?? null, kind: r.kind ?? (r.verdict?.verdict === 'accepted' ? 'acceptance' : 'execution'), sha256: recordSha, signed: !!signed, kid: r.signature?.kid ?? null, issued_at: r.issued_at ?? null, exported_by: r.exported_by ?? null },
-    run: { id: run.id ?? null, url: run.url ?? null, project: run.project ?? null, started_at: run.started_at ?? null, finished_at: run.finished_at ?? null, version: run.version ?? null, app_version: run.app_version ?? null },
-    scenario: { id: run.scenario?.id ?? null, title: run.scenario?.title ?? null, version: run.scenario?.version ?? null, file: run.scenario?.file ?? null, sha256: run.scenario?.sha256 ?? null, refs: cleanRefs(run.scenario?.refs) },
+    run: { id: run.id ?? null, url: run.url ?? null, project: run.project ?? null, started_at: run.started_at ?? null, finished_at: run.finished_at ?? null, version: run.version ?? null, app_version: run.app_version ?? null, refs: Array.isArray(run.refs) ? run.refs.filter((x) => typeof x === 'string') : [], purpose: run.purpose ?? null },
+    scenario: { id: run.scenario?.id ?? null, title: run.scenario?.title ?? null, version: run.scenario?.version ?? null, file: run.scenario?.file ?? null, sha256: run.scenario?.sha256 ?? null, refs: cleanRefs(run.scenario?.refs), lanes: flow?.lanes ?? null, sessions: flow?.sessions ?? null },
     environment: run.environment || null,
     git: run.git || null,
     tools: r.tools || null,
@@ -113,7 +121,7 @@ export function evidenceOf (record, { record_sha256: recordSha = null, signed =
     summary: r.summary || null,
     ai: r.ai || null,
     advisory: r.advisory ?? null,
-    steps: (r.steps || []).map((s) => ({ ...s, refs: cleanRefs(s.refs), criteria: (s.criteria || []).map((c) => ({ ...c, refs: cleanRefs(c.refs) })) })),
+    steps: (r.steps || []).map((s) => ({ ...s, ...placed(s), refs: cleanRefs(s.refs), criteria: (s.criteria || []).map((c) => ({ ...c, refs: cleanRefs(c.refs) })) })),
     signatures: r.signatures || [],
     decision_changes: r.decision_changes || [],
     audit: (audit || []).map(auditEntry)
@@ -130,7 +138,7 @@ export function auditEntry (a) {
 }
 
 /** The evidence document of a release (kind release): its runs' evidence and one trace matrix over all of them. */
-export function releaseEvidenceOf ({ release, runs, missing = [], org = null, issuer = null, generated_at: at = new Date().toISOString() }) {
+export function releaseEvidenceOf ({ release, runs, missing = [], org = null, issuer = null, generated_at: at = new Date().toISOString(), filter = null }) {
   return {
     schema: EVIDENCE_SCHEMA,
     kind: 'release',
@@ -141,6 +149,8 @@ export function releaseEvidenceOf ({ release, runs, missing = [], org = null, is
     runs,
     // runs of the release with no evidence: not accepted, deleted or out of reach, each with the reason
     missing,
+    // ?ref= / ?purpose= narrowed the release to the runs of one record or purpose (#126)
+    ...(filter && Object.keys(filter).length ? { filter } : {}),
     trace: runs.flatMap((r) => r.trace || [])
   }
 }
@@ -161,6 +171,7 @@ export function traceRows (ev) {
     const d = s.decision || (s.carried ? { state: 'approved', by: s.carried.approved_by, at: s.carried.approved_at, via: 'carried' } : null)
     const stepCols = { step_decision: d?.state ?? null, step_decided_by: d?.by ?? null, step_decided_at: d?.at ?? null, step_decided_via: d?.via ?? null, ...sigCols(stepSig, 'step'), step_comment: d?.note || null }
     const stepRefs = cleanRefs(s.refs)
+    const placeCols = { session: s.session?.key ?? null, session_title: s.session?.title ?? null, lane: s.lane?.index ?? null, lane_label: s.lane?.label ?? null }
     const caps = new Map((s.captures || []).map((c) => [`${c.locale}|${c.viewport}`, c]))
     for (const c of s.criteria || []) {
       const refs = [...cleanRefs(c.refs).map((x) => [x, 'criterion']), ...stepRefs.map((x) => [x, 'step']), ...scenarioRefs.map((x) => [x, 'scenario'])]
@@ -175,7 +186,7 @@ export function traceRows (ev) {
             step_id: s.id, step_title: s.title ?? null, criterion_id: c.id, criterion_text: c.text ?? null, criterion_type: c.type ?? null,
             locale: cell.locale ?? null, viewport: cell.viewport ?? null, evidence_file: cap?.path ?? null, evidence_sha256: cap?.sha256 ?? null,
             result: cell.verdict ?? null, assessed_by: cell.assessed_by ?? null, assessor: cell.assessor ?? null, advisory: !!cell.advisory,
-            ...stepCols, ...runCols
+            ...stepCols, ...runCols, ...placeCols
           })
         }
       }
@@ -287,7 +298,7 @@ export function packageReadme ({ run, service, recordSha }) {
     'record/kaloko-signoff.json  the acceptance record, signed by Kaloko (Ed25519)',
     'record/kaloko-signoff.pdf   the same record for people, with the JSON attached',
     'evidence.json               everything below in one machine-readable file (schema qawalk.evidence.v1)',
-    'trace.json, trace.csv       requirement → criterion → step, locale, viewport → screenshot (SHA-256) → result → decision',
+    'trace.json, trace.csv       requirement → criterion → step (role, lane), locale, viewport → screenshot (SHA-256) → result → decision',
     'audit.csv                   the audit trail of the run',
     'captures/                   the screenshots the record names',
     'decisions/                  files attached to step decisions (approve / return), as the record names them',

package/src/lib/lanes-core.mjs

@@ -0,0 +1,61 @@
+// Lanes (sub-processes) and sessions (roles) of a flow: which lane and which person a step belongs to, with the names
+// the canvas shows. Pure, no Node APIs: shared by the scenario layout (scenario.mjs), the quality evidence
+// (evidence-core.mjs, CLI and service) and the MCP run summary. The canvas (viewer/index.html) keeps a byte-identical
+// copy of laneLabels; test/lanes.test.mjs checks that the two stay the same.
+//
+// A scenario names its lanes in `lanes:`. Without them, its sessions draw the lanes: one per session, in declaration
+// order. The lane index of a step is resolved once, by the layout when the run is built (run.json nodes[].lane), and
+// every reader takes it from there.
+
+/** Lane index of each session when the sessions draw the lanes (no `lanes` declared); null when `lanes` are declared. */
+export function sessionLanes (lanes, sessions) {
+  if (!sessions || (Array.isArray(lanes) && lanes.length)) return null
+  return new Map(Object.keys(sessions).map((k, i) => [k, i]))
+}
+
+/**
+ * Names of the lanes, index = lane: the scenario's `lanes`, or (none declared) the titles of its sessions in
+ * declaration order. A localized title reads in `locale`, else its default, else its first language. Self-contained:
+ * the canvas carries the same function.
+ */
+export function laneLabels (lanes, sessions, locale) {
+  const text = (v) => v == null ? '' : typeof v === 'string' ? v : (v[locale] ?? v.default ?? Object.values(v)[0] ?? '')
+  return Array.isArray(lanes) && lanes.length ? lanes.map((l) => text(l)) : Object.entries(sessions || {}).map(([k, s]) => text(s?.title) || k)
+}
+
+/** A plain or localized title as text (the same reading as laneLabels). */
+export const textOf = (v, locale = null) => v == null ? '' : typeof v === 'string' ? v : (v[locale] ?? v.default ?? Object.values(v)[0] ?? '')
+
+/**
+ * Where each step of a run manifest (qawalk.run.v1) sits: Map step id → { session: { key, title } | null,
+ * lane: { index, label } | null }. label is null for a lane without a name (a flow without lanes or sessions, or an
+ * extra row the layout opened for an alternative branch).
+ */
+export function stepPlaces (manifest, locale = null) {
+  const m = manifest || {}
+  const labels = laneLabels(m.lanes, m.sessions, locale)
+  const out = new Map()
+  for (const n of m.nodes || []) {
+    const key = typeof n.session === 'string' && n.session ? n.session : null
+    out.set(n.id, {
+      session: key ? { key, title: textOf(m.sessions?.[key]?.title, locale) || key } : null,
+      lane: Number.isInteger(n.lane) ? { index: n.lane, label: labels[n.lane] || null } : null
+    })
+  }
+  return out
+}
+
+/**
+ * The lanes and sessions of a run manifest as a portal lists them: lanes [{ index, label }] (every named lane and
+ * every lane a step sits in) and sessions [{ key, title }] in declaration order.
+ */
+export function flowStructure (manifest, locale = null) {
+  const m = manifest || {}
+  const labels = laneLabels(m.lanes, m.sessions, locale)
+  const used = new Set(labels.map((_, i) => i))
+  for (const n of m.nodes || []) if (Number.isInteger(n.lane)) used.add(n.lane)
+  return {
+    lanes: [...used].sort((a, b) => a - b).map((index) => ({ index, label: labels[index] || null })),
+    sessions: Object.entries(m.sessions || {}).map(([key, s]) => ({ key, title: textOf(s?.title, locale) || key }))
+  }
+}

package/src/lib/run-refs.mjs

@@ -0,0 +1,55 @@
+// Run references and purpose (#126): the external records a run serves (a change-control record CC-2026-001, a
+// validation protocol) and why it was walked (dry_run, formal, smoke). Set with kaloko start --ref / --purpose or
+// KALOKO_REFS / KALOKO_PURPOSE, kept in the run manifest (refs, purpose) and checked again by the service
+// (worker/src/manifest.js), which stores them so GET …/runs?ref= and ?purpose= can filter. No node: imports: the
+// Worker uses it too.
+
+/** A reference as people write record ids: letters, digits and . _ - / : # +, starting with a letter or digit. */
+export const RUN_REF = /^[A-Za-z0-9][A-Za-z0-9._:/#+-]{0,79}$/
+export const MAX_RUN_REFS = 20
+export const RUN_PURPOSES = ['dry_run', 'formal', 'smoke']
+
+/**
+ * References from options or the environment: an array of values (--ref repeated) or one string, each split at
+ * commas and white space. Trimmed, empty pieces dropped, duplicates removed in order. Not validated: see refProblems.
+ */
+export function splitRunRefs (value) {
+  const list = Array.isArray(value) ? value : value == null || value === true || value === false ? [] : [value]
+  const out = []
+  for (const v of list) for (const piece of String(v).split(/[\s,]+/)) if (piece && !out.includes(piece)) out.push(piece)
+  return out
+}
+
+/** What is wrong with a list of references ([] when it is fine). */
+export function refProblems (refs) {
+  if (!Array.isArray(refs)) return ['refs must be a list of references.']
+  const problems = []
+  if (refs.length > MAX_RUN_REFS) problems.push(`A run takes at most ${MAX_RUN_REFS} references; this one has ${refs.length}.`)
+  for (const r of refs) if (typeof r !== 'string' || !RUN_REF.test(r)) problems.push(`"${String(r).slice(0, 100)}" is not a reference Kaloko keeps: up to 80 letters, digits and . _ - / : # +, starting with a letter or digit.`)
+  if (new Set(refs).size !== refs.length) problems.push('refs names a reference twice.')
+  return problems
+}
+
+/**
+ * The references and purpose of kaloko start: --ref (repeated or comma separated) or else KALOKO_REFS, --purpose or
+ * else KALOKO_PURPOSE. Returns { refs, purpose, problems }; problems name the option or variable they came from.
+ */
+export function startRefs (args = {}, env = {}) {
+  const fromFlag = args.ref !== undefined && args.ref !== true && !(Array.isArray(args.ref) && args.ref.every((v) => v === true))
+  const refs = splitRunRefs(fromFlag ? [].concat(args.ref).filter((v) => v !== true) : env.KALOKO_REFS)
+  const problems = []
+  if (args.ref === true || (Array.isArray(args.ref) && args.ref.includes(true))) problems.push('--ref takes a reference, e.g. --ref CC-2026-001.')
+  for (const p of refProblems(refs)) problems.push(`${fromFlag ? '--ref' : 'KALOKO_REFS'}: ${p}`)
+  const given = typeof args.purpose === 'string' ? args.purpose : args.purpose === true ? '' : env.KALOKO_PURPOSE
+  const purpose = normalizePurpose(given)
+  if (args.purpose === true) problems.push(`--purpose takes one of ${RUN_PURPOSES.join(', ')}.`)
+  else if (purpose === undefined) problems.push(`${typeof args.purpose === 'string' ? '--purpose' : 'KALOKO_PURPOSE'} is "${String(given).slice(0, 40)}"; use ${RUN_PURPOSES.join(', ')}.`)
+  return { refs, purpose: purpose || null, problems }
+}
+
+/** dry_run | formal | smoke from what people type (dry-run, Formal); null when empty; undefined when not a purpose. */
+export function normalizePurpose (value) {
+  if (value == null || value === '') return null
+  const p = String(value).trim().toLowerCase().replace(/-/g, '_')
+  return RUN_PURPOSES.includes(p) ? p : undefined
+}

package/src/lib/run.mjs

@@ -37,7 +37,7 @@ export function newRunId (scenario, date = new Date()) {
   return { id: `${today(date)}-${slugify(scenario.id)}-${short}`, short }
 }
 
-export async function createRun ({ output, scenario, scenarioFile, env, scope, git, executor, root, project = null, issue = null, appVersion = null, product = null, pii = null }) {
+export async function createRun ({ output, scenario, scenarioFile, env, scope, git, executor, root, project = null, issue = null, refs = [], purpose = null, appVersion = null, product = null, pii = null }) {
   const { id, short } = newRunId(scenario)
   const dir = resolve(root, output, id)
   await mkdir(dir, { recursive: true })
@@ -54,6 +54,9 @@ export async function createRun ({ output, scenario, scenarioFile, env, scope, g
     executor,
     project,
     issue,
+    // the records the run serves (change control, protocol) and why it was walked (#126; src/lib/run-refs.mjs)
+    ...(refs?.length ? { refs } : {}),
+    ...(purpose ? { purpose } : {}),
     app_version: appVersion,
     // personal data hidden in every capture (#64): { mode: redact | pseudonymize, allow }
     ...(pii ? { pii } : {}),

package/src/lib/scenario.mjs

@@ -4,6 +4,7 @@ import { schemaErrors } from './schema.mjs'
 import { UserError } from './util.mjs'
 import { expandPacks } from './packs.mjs'
 import { jsGuard } from './assertions.mjs'
+import { sessionLanes } from './lanes-core.mjs'
 
 // a scenario holds thousands of values, not millions: aliases (&a, *a) can expand a few kilobytes of YAML into
 // billions that validation and its JSON copy would walk ("billion laughs"), so the expanded size has a ceiling
@@ -156,7 +157,7 @@ export function layout (scenario) {
   const taken = new Set()
   const claim = (c, l) => { while (taken.has(`${c}:${l}`)) l++; taken.add(`${c}:${l}`); return l }
   // sessions without explicit lanes: one swimlane per person, in declaration order
-  const sessionLane = scenario.sessions && !(scenario.lanes || []).length ? new Map(Object.keys(scenario.sessions).map((k, i) => [k, i])) : null
+  const sessionLane = sessionLanes(scenario.lanes, scenario.sessions)
   for (const n of [...nodes].sort((a, b) => col.get(a.id) - col.get(b.id) || order.get(a.id) - order.get(b.id))) {
     let wanted = n.lane
     if (wanted == null && sessionLane && n.session != null && sessionLane.has(n.session)) wanted = sessionLane.get(n.session)

package/src/lib/signoff.mjs

@@ -143,6 +143,10 @@ export async function evidenceCmd ({ config, args, say, client, runId = null })
     const product = typeof args.product === 'string' ? args.product : Object.keys(config.products || {}).length === 1 ? Object.keys(config.products)[0] : (config.project || null)
     if (!product) throw new UsageError('Name the product of the release: --product <slug>.')
     path = `/orgs/${config.org}/evidence?product=${encodeURIComponent(product)}&version=${encodeURIComponent(release)}`
+    // only the release's runs of one record or purpose (#126)
+    const ref = typeof args.ref === 'string' ? args.ref : null
+    if (ref) path += `&ref=${encodeURIComponent(ref)}`
+    if (typeof args.purpose === 'string') path += `&purpose=${encodeURIComponent(args.purpose)}`
   } else path = `/orgs/${config.org}/runs/${encodeURIComponent(runId)}/evidence`
   const ev = await client.request('GET', path)
   const text = args.csv ? traceCsv(ev.trace || []) : JSON.stringify(ev, null, 2)

package/viewer/index.html

@@ -165,6 +165,8 @@ a.pr:hover{text-decoration-color:var(--ink)}
 .run__env--staging{background:var(--partial-bg);color:var(--partial-ink)}
 .run__env--production{background:var(--fail-bg);color:var(--fail-ink)}
 .run__env--review{background:var(--pass-bg);color:var(--pass-ink)}
+.run__purpose{font-size:11px;font-weight:600;padding:1px 6px;border-radius:4px;border:1px solid var(--line);color:var(--muted);white-space:nowrap}
+.run__purpose--formal{border-color:currentColor;color:var(--ink)}
 .bar5{display:flex;height:5px;border-radius:3px;overflow:hidden;background:var(--skip-bg);min-width:60px}
 .bar5 i{display:block}
 .steps{list-style:none;margin:0;padding:0 8px 16px}
@@ -355,6 +357,8 @@ body.embed .helpwrap{display:none}
 .viewport{position:relative;overflow:hidden;cursor:grab;touch-action:none;
   background-color:var(--ground);background-image:radial-gradient(var(--dots) 1px,transparent 1.2px);background-size:22px 22px}
 .viewport.dragging{cursor:grabbing}
+/* a pan never selects the lane headings, titles and thumbnails it crosses; the class lives only for the drag */
+html.is-panning,html.is-panning *{user-select:none;-webkit-user-select:none}
 .world{position:absolute;left:0;top:0;transform-origin:0 0}
 .edges{position:absolute;left:0;top:0;overflow:visible;pointer-events:none}
 .edges path{fill:none;stroke:var(--edge);stroke-width:1.6}
@@ -363,6 +367,8 @@ body.embed .helpwrap{display:none}
 .edges.hl path{opacity:.12}.edges.hl path.on{opacity:1;stroke:var(--ink);stroke-width:2.6}
 .lane-band{position:absolute;border-radius:14px;background:color-mix(in srgb,var(--panel) 38%,transparent);border:1px solid color-mix(in srgb,var(--line) 70%,transparent);pointer-events:none}
 .lane-band:nth-child(even){background:color-mix(in srgb,var(--panel-2,var(--panel)) 55%,transparent)}
+/* #lane=<index>: the lane a link points to */
+.lane-band.is-on{border:2px solid var(--line-strong);box-shadow:0 0 0 4px var(--accent)}
 .lane-head{position:absolute;left:16px;top:-30px;font-size:14px;font-weight:700;color:var(--ink);white-space:nowrap;display:flex;gap:10px;align-items:baseline}
 .lane-head small{font-size:12px;font-weight:500;color:var(--muted)}
 .world.far .jev,.world.far .node__foot{visibility:hidden}
@@ -2298,7 +2304,13 @@ function drawEdges () {
   BOXES = new Map(); for (const el of $('nodes').querySelectorAll('.node[data-id]')) BOXES.set(el.dataset.id, { x: el.offsetLeft, y: el.offsetTop, w: el.offsetWidth, h: el.offsetHeight });
   try { return drawEdgesNow(); } finally { BOXES = null; }
 }
-const laneNamesOf = () => (RUN.lanes || []).length ? RUN.lanes : sessions().map(sessTitle);
+/** Names of the lanes, index = lane: the scenario's lanes, or one per session. The same function as laneLabels in
+    src/lib/lanes-core.mjs (the evidence names lanes with it; test/lanes.test.mjs keeps the two identical). */
+function laneLabels (lanes, sessions, locale) {
+  const text = (v) => v == null ? '' : typeof v === 'string' ? v : (v[locale] ?? v.default ?? Object.values(v)[0] ?? '')
+  return Array.isArray(lanes) && lanes.length ? lanes.map((l) => text(l)) : Object.entries(sessions || {}).map(([k, s]) => text(s?.title) || k)
+}
+const laneNamesOf = () => laneLabels(RUN.lanes, RUN.sessions, S.loc);
 /** Box of every lane from its rendered cards; bands and edge corridors use it. */
 function laneBoxes () {
   const out = new Map();
@@ -2351,7 +2363,7 @@ function drawEdgesNow () {
   $('edges').setAttribute('width', maxX + 100); $('edges').setAttribute('height', maxY + 200);
   // lanes: a band with a header (title, steps, passed) behind the cards of each lane
   const names = laneNamesOf();
-  const bands = names.length > 1 ? [...lanesBox.entries()].sort(([a], [b]) => a - b).map(([i, L]) => `<div class="lane-band" data-lane="${i}" style="left:${L.x1 - 24}px;top:${L.y1 - 20}px;width:${L.x2 - L.x1 + 48}px;height:${L.y2 - L.y1 + 40}px"><span class="lane-head">${esc(names[i] || '')}<small>${L.n} ${T('stepsWord')} · ${L.pass}/${L.n} ${T('passedWord')}</small></span></div>`) : [];
+  const bands = names.length > 1 ? [...lanesBox.entries()].sort(([a], [b]) => a - b).map(([i, L]) => `<div class="lane-band${S.laneHl === i ? ' is-on' : ''}" data-lane="${i}" style="left:${L.x1 - 24}px;top:${L.y1 - 20}px;width:${L.x2 - L.x1 + 48}px;height:${L.y2 - L.y1 + 40}px"><span class="lane-head">${esc(names[i] || '')}<small>${L.n} ${T('stepsWord')} · ${L.pass}/${L.n} ${T('passedWord')}</small></span></div>`) : [];
   $('bands').innerHTML = bands.join('');
   const lanes = names.length > 1 ? [] : names.map((l, i) => { const first = RUN.nodes.filter((n) => n.lane === i).sort((a, b) => a.col - b.col)[0]; return l && first ? `<span class="lane-label" style="left:${nodePos(first).x}px;top:${Y0 + i * LANEH() - 34}px">${esc(l)}</span>` : ''; });
   $('labels').innerHTML = labels.join('') + lanes.join('');
@@ -2361,6 +2373,16 @@ function hlEdges (id) {
   const svg = $('edges'); svg.classList.toggle('hl', !!id);
   svg.querySelectorAll('path[data-from]').forEach((p) => p.classList.toggle('on', !!id && (p.dataset.from === id || p.dataset.to === id)));
 }
+/** A lane from the steps panel or a #lane= link: fitted on the map, its group in view in the index. */
+function showLane (i) {
+  if (S.mode === 'index') { const k = (S.ri?.entries || []).findIndex((x) => x.type === 'group' && x.label === laneNamesOf()[i]); if (k >= 0) $('riList').scrollTop = S.ri.tops[k]; return; }
+  fitLane(i);
+}
+/** #lane=<index> highlights that lane's band (null: none). */
+function markLane (i) {
+  S.laneHl = i;
+  $('bands').querySelectorAll('.lane-band').forEach((b) => b.classList.toggle('is-on', Number(b.dataset.lane) === i));
+}
 function fitLane (i) {
   const L = laneBoxes().get(i), r = $('vp').getBoundingClientRect(); if (!L || !r.width) return;
   // the whole lane when it fits at a readable zoom, else its start at the readable zoom
@@ -2954,12 +2976,12 @@ function focusNode (id) { const el = document.querySelector(`.node[data-id="${CS
 
 function wireCanvas () {
   const vp = $('vp'); let drag = null;
-  vp.addEventListener('pointerdown', (e) => { if (e.target.closest('.node,.hud') || pinch) return; drag = { id: e.pointerId, x: e.clientX, y: e.clientY, vx: S.view.x, vy: S.view.y }; vp.setPointerCapture(e.pointerId); vp.classList.add('dragging'); });
+  vp.addEventListener('pointerdown', (e) => { if (e.target.closest('.node,.hud') || pinch) return; drag = { id: e.pointerId, x: e.clientX, y: e.clientY, vx: S.view.x, vy: S.view.y }; vp.setPointerCapture(e.pointerId); vp.classList.add('dragging'); document.documentElement.classList.add('is-panning'); getSelection()?.removeAllRanges(); });
   vp.addEventListener('pointermove', (e) => { if (!drag || e.pointerId !== drag.id) return; S.view.x = drag.vx + e.clientX - drag.x; S.view.y = drag.vy + e.clientY - drag.y; applyView(); });
   // two fingers pinch-zoom the canvas around their midpoint and pan with it (the page itself never zooms)
   let pinch = null;
   const two = (e) => { const [a, b] = e.touches, r = vp.getBoundingClientRect(); return { d: Math.hypot(a.clientX - b.clientX, a.clientY - b.clientY) || 1, x: (a.clientX + b.clientX) / 2 - r.left, y: (a.clientY + b.clientY) / 2 - r.top }; };
-  vp.addEventListener('touchstart', (e) => { if (e.touches.length !== 2) return; drag = null; vp.classList.remove('dragging'); const g = two(e); pinch = { ...g, k: S.view.k }; }, { passive: true });
+  vp.addEventListener('touchstart', (e) => { if (e.touches.length !== 2) return; drag = null; vp.classList.remove('dragging'); document.documentElement.classList.remove('is-panning'); const g = two(e); pinch = { ...g, k: S.view.k }; }, { passive: true });
   vp.addEventListener('touchmove', (e) => {
     if (!pinch || e.touches.length !== 2) return; e.preventDefault();
     const g = two(e); S.view.x += g.x - pinch.x; S.view.y += g.y - pinch.y; pinch.x = g.x; pinch.y = g.y;
@@ -2967,7 +2989,7 @@ function wireCanvas () {
   }, { passive: false });
   vp.addEventListener('touchend', (e) => { if (e.touches.length < 2) pinch = null; }, { passive: true });
   vp.addEventListener('touchcancel', () => { pinch = null; }, { passive: true });
-  const end = () => { drag = null; vp.classList.remove('dragging'); };
+  const end = () => { drag = null; vp.classList.remove('dragging'); document.documentElement.classList.remove('is-panning'); };
   vp.addEventListener('pointerup', end); vp.addEventListener('pointercancel', end);
   // presence: my cursor to the others; dragging or zooming myself ends following someone
   vp.addEventListener('pointermove', presenceCursor);
@@ -3053,15 +3075,15 @@ function renderChrome () {
   // a live draft says so in the bar on a phone too, where the meta line under the title is hidden
   $('liveTag').hidden = !(isDesign() && isDraft()); $('liveTag').textContent = T('liveShared');
   if (isDesign()) $('runMeta').textContent = [isDraft() ? `${T('draft')} #${RUN.draft.seq}${RUN.draft.branch !== 'main' ? ` @${RUN.draft.branch}` : ''} · ${T('liveShared')}` : `${T('version')} v${RUN.version}${RUN.version_name ? ` · ${RUN.version_name}` : ''}`, fmtDate(RUN.started_at), RUN.verdict && RUN.verdict.verdict !== 'pending' && T(RUN.verdict.verdict), (RUN.references?.design || RUN.design_reference_id) === RUN.id && T('designRef')].filter(Boolean).join(' · ');
-  else $('runMeta').textContent = [fmtDate(RUN.started_at), RUN.environment.name, g.branch && `${g.branch} @ ${g.commit}`, g.author, g.pr && `PR #${g.pr.number}`, RUN.verdict && RUN.verdict.verdict !== 'pending' && `${T(RUN.verdict.verdict)}${RUN.verdict.baseline ? ' · ' + T('baseline') : ''}`].filter(Boolean).join(' · ');
+  else $('runMeta').textContent = [fmtDate(RUN.started_at), RUN.environment.name, purposeLabel(RUN.purpose), runRefs().join(', '), g.branch &&`${g.branch} @ ${g.commit}`, g.author, g.pr && `PR #${g.pr.number}`, RUN.verdict && RUN.verdict.verdict !== 'pending' && `${T(RUN.verdict.verdict)}${RUN.verdict.baseline ? ' · ' + T('baseline') : ''}`].filter(Boolean).join(' · ');
   document.title = `${RUN.scenario.id} · Kaloko`;
   const hist = [...(RUN.history || []), { id: RUN.id, started_at: RUN.started_at, current: true }].sort((a, b) => b.started_at.localeCompare(a.started_at));
   const i = hist.findIndex((h) => h.current);
   const c = { pass: RUN.summary.pass, partial: RUN.summary.partial, fail: RUN.summary.fail, skip: RUN.summary.skip };
-  $('runcard').innerHTML = `<div class="runcard__top"><span class="runcard__when">${fmtDate(RUN.started_at)}</span><span class="run__env run__env--${esc(RUN.environment.name)}">${esc(RUN.environment.name)}</span>${RUN.pii?.hidden ? `<span class="run__pii" title="${esc(T('piiRun')(RUN.pii.mode))}">${esc(RUN.pii.mode === 'pseudonymize' ? T('piiTagFake') : T('piiTag'))}</span>` : ''}
+  $('runcard').innerHTML = `<div class="runcard__top"><span class="runcard__when">${fmtDate(RUN.started_at)}</span><span class="run__env run__env--${esc(RUN.environment.name)}">${esc(RUN.environment.name)}</span>${purposeLabel(RUN.purpose) ? `<span class="run__purpose run__purpose--${esc(RUN.purpose)}" title="${esc(T('purposeWord'))}">${esc(purposeLabel(RUN.purpose))}</span>` : ''}${RUN.pii?.hidden ? `<span class="run__pii" title="${esc(T('piiRun')(RUN.pii.mode))}">${esc(RUN.pii.mode === 'pseudonymize' ? T('piiTagFake') : T('piiTag'))}</span>` : ''}
     <span class="runcard__nav"><a class="icon-btn" aria-label="${T('older')}" ${hist[i + 1] ? `href="${runHref(hist[i + 1].id)}"` : 'aria-disabled="true" style="opacity:.35"'}>${ICON.prev}</a><a class="icon-btn" aria-label="${T('newer')}" ${hist[i - 1] ? `href="${runHref(hist[i - 1].id)}"` : 'aria-disabled="true" style="opacity:.35"'}>${ICON.next}</a></span></div>
     ${bar5(c)}
-    <dl>${g.branch ? `<dt>${T('branch')}</dt><dd class="mono">${esc(g.branch)}</dd><dt>${T('commit')}</dt><dd><span class="mono">${esc(g.commit)}</span> ${esc(g.message)}</dd><dt>${T('author')}</dt><dd><span class="who"><span class="av">${esc(initials(g.author))}</span>${esc(g.author)}</span></dd><dt>${T('pr')}</dt><dd>${prLink(g.pr)}</dd>` : ''}${RUN.uploaded_by ? `<dt>${g.branch ? T('uploadedBy') : T('author')}</dt><dd><span class="who"><span class="av">${esc(initials(RUN.uploaded_by))}</span>${esc(RUN.uploaded_by)}</span></dd>` : ''}${RUN.issue ? `<dt>${T('issue')}</dt><dd>${issueRef(RUN.issue)}</dd>` : ''}
+    <dl>${g.branch ? `<dt>${T('branch')}</dt><dd class="mono">${esc(g.branch)}</dd><dt>${T('commit')}</dt><dd><span class="mono">${esc(g.commit)}</span> ${esc(g.message)}</dd><dt>${T('author')}</dt><dd><span class="who"><span class="av">${esc(initials(g.author))}</span>${esc(g.author)}</span></dd><dt>${T('pr')}</dt><dd>${prLink(g.pr)}</dd>` : ''}${RUN.uploaded_by ? `<dt>${g.branch ? T('uploadedBy') : T('author')}</dt><dd><span class="who"><span class="av">${esc(initials(RUN.uploaded_by))}</span>${esc(RUN.uploaded_by)}</span></dd>` : ''}${RUN.issue ? `<dt>${T('issue')}</dt><dd>${issueRef(RUN.issue)}</dd>` : ''}${runRefs().length ? `<dt>${T('runRefsLabel')}</dt><dd>${runRefs().map((r) => `<span class="ref">${esc(r)}</span>`).join('')}</dd>` : ''}
       ${RUN.scenario.platform ? `<dt>${T('platformWord')}</dt><dd>${esc(platformLabel(RUN.scenario.platform))}${(() => { const d = screens().flatMap((n) => Object.values(n.captures?.[S.loc] || {})).map((c) => c?.device).find(Boolean); return d ? ` · ${esc(d)}` : ''; })()}</dd>` : ''}
       <dt>${T('env')}</dt><dd class="mono">${RUN.environment.kind === 'design' ? `${esc(RUN.environment.name)}${RUN.environment.name !== 'design' ? ` · ${T('designEnv')}` : ''}` : esc(RUN.environment.base_url == null ? '—' : typeof RUN.environment.base_url === 'string' ? RUN.environment.base_url : loc(RUN.environment.base_url))}${RUN.environment.readonly ? ' · readonly' : ''}</dd>
       ${RUN.pii?.hidden ? `<dt>${T('piiWord')}</dt><dd>${esc(T('piiRun')(RUN.pii.mode))}</dd>` : ''}
@@ -3074,7 +3096,7 @@ function renderChrome () {
     : laneNamesOf().length > 1
       ? laneNamesOf().map((name, i) => { const mine = order.filter((n) => n.lane === i); if (!mine.length) return ''; const c = { pass: mine.filter((n) => nodeSt(n) === 'pass').length }; return `<h3 data-lane="${i}" title="${esc(T('fitLane'))}">${esc(name)} <small class="muted">${c.pass}/${mine.length}</small></h3>${mine.map(stepLi).join('')}`; }).join('')
       : order.map(stepLi).join('');
-  $('steps').onclick = (e) => { const ln = e.target.closest('[data-lane]'); if (ln) { if (S.mode === 'index') { const k = (S.ri?.entries || []).findIndex((x) => x.type === 'group' && x.label === laneNamesOf()[Number(ln.dataset.lane)]); if (k >= 0) $('riList').scrollTop = S.ri.tops[k]; return; } fitLane(Number(ln.dataset.lane)); return; } const h = e.target.closest('[data-sess]'); if (h) { S.sess = S.sess === h.dataset.sess ? null : h.dataset.sess; renderAll(); return; } const b = e.target.closest('[data-step]'); if (!b) return; if (S.mode === 'index') riFocus(b.dataset.step); else if (byId(b.dataset.step)?.kind === 'stack') { focusNode(b.dataset.step); openStack(b.dataset.step); } else focusNode(b.dataset.step); if (innerWidth <= 1100) { S.left = false; setPanels(); } };
+  $('steps').onclick = (e) => { const ln = e.target.closest('[data-lane]'); if (ln) { showLane(Number(ln.dataset.lane)); return; } const h = e.target.closest('[data-sess]'); if (h) { S.sess = S.sess === h.dataset.sess ? null : h.dataset.sess; renderAll(); return; } const b = e.target.closest('[data-step]'); if (!b) return; if (S.mode === 'index') riFocus(b.dataset.step); else if (byId(b.dataset.step)?.kind === 'stack') { focusNode(b.dataset.step); openStack(b.dataset.step); } else focusNode(b.dataset.step); if (innerWidth <= 1100) { S.left = false; setPanels(); } };
   $('scFoot').innerHTML = `${issFootHtml()}${RUN.project ? `<span class="mono">${esc(RUN.project.slug)}</span> · ` : ''}${RUN.issue?.url ? `<a class="pr" href="${esc(webHref(RUN.issue.url))}" target="_blank" rel="noopener">${esc(RUN.issue.repo ? RUN.issue.repo + '#' : '#')}${esc(String(RUN.issue.number))}</a> · ` : ''}<code>${esc(RUN.scenario.file || '')}</code>${RUN.scenario.version ? ` · v${esc(RUN.scenario.version)}` : ''}<br><span class="mono">${esc(RUN.id)}</span>`;
 }
 // the summary panel before the cards: the cards measure themselves, and that one layout then covers the panel too
@@ -3935,6 +3957,12 @@ function applyHash () {
   if (pres && byId(pres)) { if (p.get('loc') && RUN.scope.locales.includes(p.get('loc')) && p.get('loc') !== S.loc) { S.loc = p.get('loc'); renderAll(); } ptOpen(pres, p.get('vp')); return; }
   if (!$('pt').hidden) { $('pt').hidden = true; $('pt').innerHTML = ''; }
   const step = p.get('step');
+  // #session=<key>: that person's steps stand out across the lanes (as picking them under People does)
+  if (p.has('session')) { const k = sessions().includes(p.get('session')) ? p.get('session') : null; if (k !== S.sess) { S.sess = k; renderAll(); } }
+  // #lane=<index>: that lane's band highlighted and fitted (a sub-process of the flow)
+  const lane = /^\d+$/.test(p.get('lane') || '') && RUN.nodes.some((n) => (n.lane || 0) === Number(p.get('lane'))) ? Number(p.get('lane')) : null;
+  if (lane !== (S.laneHl ?? null)) markLane(lane);
+  if (lane !== null && !step) showLane(lane);
   if (step && step.includes('~') && !byId(step) && byId(step.split('~')[0])?.kind === 'stack') { loadStack(byId(step.split('~')[0])).then((d) => { if (d) { S.itemList = d.items.map((it) => ensureItemNode(byId(step.split('~')[0]), d, it).id); applyHash(); } }); return; }
   if (!step || !byId(step)) return;
   if (p.get('loc') && RUN.scope.locales.includes(p.get('loc')) && p.get('loc') !== S.loc) { S.loc = p.get('loc'); renderAll(); }
@@ -5554,6 +5582,14 @@ document.addEventListener('click', (e) => {
   if (t) { t.focus(); t.scrollIntoView({ block: 'center' }); }
 });
 
+/* ---------- Run references and purpose (#126): the records a run serves (kaloko start --ref) and why it was walked ---------- */
+Object.assign(I18N.cs, { runRefsLabel: 'Navázané záznamy', purposeWord: 'Účel', purpose_dry_run: 'Zkušební běh', purpose_formal: 'Formální běh', purpose_smoke: 'Smoke test' });
+Object.assign(I18N.en, { runRefsLabel: 'Linked records', purposeWord: 'Purpose', purpose_dry_run: 'Dry run', purpose_formal: 'Formal run', purpose_smoke: 'Smoke test' });
+/** The run's references as strings (none for runs made before #126). */
+const runRefs = () => (Array.isArray(RUN.refs) ? RUN.refs : []).filter((x) => typeof x === 'string' && x);
+/** dry_run | formal | smoke in the reader's language; '' when the run names no purpose. */
+const purposeLabel = (p) => (['dry_run', 'formal', 'smoke'].includes(p) ? T(`purpose_${p}`) : '');
+
 /* ---------- Personal data (#64): the run's "personal data hidden" flag and the masked places of a capture ---------- */
 Object.assign(I18N.cs, {
   piiTag: 'Osobní údaje skryty', piiTagFake: 'Osobní údaje nahrazeny', piiWord: 'Osobní údaje', piiBox: 'Skryté osobní údaje', cc: 'Kopie',