kaloko 0.16.1 → 0.18.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
@@ -155,6 +162,13 @@ jobs:
 Uploads go by content hash: captures that did not change since an earlier run
 are not sent again, and an interrupted `share` picks up where it stopped.
 
+With the Kaloko GitHub App (Team and up), each pull request also gets one
+`Kaloko` check on its newest commit. It turns green when the runs shared for
+that commit pass, whether they came from this workflow, a coding agent in the
+cloud or a laptop. Branch protection can require it, and labels and
+`/kaloko skip <reason>` control a single pull request. Details:
+`skills/kaloko/reference/ci.md`.
+
 ## When a screenshot is not enough
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "description": "Your AI agents build; Kaloko walks every screen, puts it on one canvas and records who approved what.",
   "keywords": [
     "qa",

package/schemas/config.v1.json

@@ -136,6 +136,21 @@
         "site_contacts": { "type": "boolean", "default": true, "description": "kaloko share takes the site's own contacts for not personal data: e-mails on the environment's domain, e-mails and phone numbers in the page footer, and those of an Organization or ContactPoint in JSON-LD. false checks them like any other value." }
       }
     },
+    "github": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The Kaloko check on pull requests (#141). The service reads it from the base branch; it may only make the check stricter than Settings on Kaloko.",
+      "properties": {
+        "checks": { "enum": ["off", "manual", "auto", "strict"], "description": "manual: only on request (label kaloko:run, /kaloko walk); auto: every pull request, the scenarios its change reaches; strict: every pull request, all scenarios, review required." },
+        "scope": { "enum": ["affected", "all"] },
+        "require_review": { "type": "boolean", "description": "Also post Kaloko review, which turns green when the runs are accepted." },
+        "drafts": { "enum": ["wait", "run"], "description": "wait: no check on a draft pull request until it is ready for review." },
+        "skip_authors": { "type": "array", "items": { "type": "string" }, "description": "Only in Settings: skipping authors would loosen the check, so the file's list is ignored." },
+        "skip_by": { "enum": ["write", "maintain", "admin"], "description": "The access a person needs to skip a pull request." },
+        "author_may_skip": { "type": "boolean" },
+        "wait_hours": { "type": "integer", "minimum": 1, "maximum": 336, "description": "strict: hours to wait for a run before the check times out." }
+      }
+    },
     "share": {
       "type": "object",
       "additionalProperties": false,

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

@@ -116,6 +116,23 @@
         "sha": {
           "type": "string",
           "description": "Full commit hash (GitHub check runs need it)."
+        },
+        "repo": {
+          "type": "string",
+          "description": "owner/name of the origin remote (kaloko 0.18+): the service finds the pull request by commit when pr is missing."
+        },
+        "host": {
+          "type": "string",
+          "enum": ["github", "gitlab", "other"],
+          "description": "Where the origin remote lives."
+        },
+        "prefix": {
+          "type": "string",
+          "description": "The project's folder inside the repository (monorepos), without a trailing slash."
+        },
+        "dirty": {
+          "type": "boolean",
+          "description": "Tracked files differed from the commit when the run started: the run does not count for the commit's GitHub check."
         }
       }
     },
@@ -332,6 +349,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

@@ -168,6 +168,10 @@ only when a person says that value may be uploaded.
   [reference/recording.md](reference/recording.md)
 - CI: a workflow that walks each pull request's preview deployment and
   comments on it (`kaloko ci github|gitlab`): [reference/ci.md](reference/ci.md)
+- The `Kaloko` check on a pull request, what makes it pass, `kaloko ci plan`,
+  labels and `/kaloko` commands, and walking from a coding agent in the cloud
+  (commit first, a dirty tree does not count; never skip the check yourself):
+  [reference/ci.md#the-kaloko-check-on-pull-requests](reference/ci.md#the-kaloko-check-on-pull-requests)
 - Environments, access (gates, accounts, sign-in), e-mails, readonly and
   production rules, and what is yours to arrange for the project's stack:
   [reference/environments.md](reference/environments.md)

package/skills/kaloko/reference/ci.md

@@ -30,6 +30,10 @@ the deployment):
    `walk --ephemeral --affected` and `share --pr` (one comment per scenario,
    updated on later pushes).
 
+Before the loop, the workflow runs `kaloko ci plan` (see
+[The Kaloko check on pull requests](#the-kaloko-check-on-pull-requests)), so
+the check on the pull request knows which scenarios to wait for.
+
 `kaloko ci` also adds the `preview` environment to `kaloko.config.yml` with
 `base_url: ${KALOKO_PREVIEW_URL}`. Scenarios that list `environments:` must
 include `preview`, or `start` refuses them; the command says which.
@@ -67,6 +71,85 @@ in the newest shared run of the scenario count too, so a fresh CI checkout
 maps routes as well as a laptop with earlier runs. See
 [execution.md](execution.md#only-what-changed).
 
+## The Kaloko check on pull requests
+
+With the Kaloko GitHub App installed (an organization admin: Settings →
+Integrations → GitHub), every pull request in a connected repository gets one
+check named `Kaloko` on its newest commit. It does not walk anything itself:
+it waits for the runs shared for that commit, from a coding agent in the
+cloud, a person's machine or this workflow, and decides from them.
+
+| The check says | When |
+|---|---|
+| success | every scenario the change reaches has a run on this commit without failing steps, or nothing reaches a scenario |
+| failure | a run on this commit has a failing step (in strict mode a partial one too) |
+| in progress | a reached scenario has no run on this commit yet; the summary says how to get one |
+| neutral | the repository has no scenario yet, or only code Kaloko cannot map without the repository changed (auto mode) |
+| skipped | someone with the right access skipped it; the summary names them and their reason |
+
+Runs of a dirty working tree (tracked files differ from the commit) are
+listed but do not count: commit first, then walk. A new push supersedes the
+old commit's check. The optional `Kaloko review` check follows the people's
+decision (accepted, returned) on those runs.
+
+Which scenarios a change reaches: the service maps the pull request's files
+onto the steps' paths and captured URLs, like `kaloko affected` without the
+repository. `kaloko ci plan` sends what `kaloko affected` found (it follows
+imports and `affects:` globs), which wins:
+
+```bash
+kaloko ci plan                         # every scenario of the config, for HEAD
+kaloko ci plan --scenario qa/flows/checkout.yml --none   # this commit reaches nothing there
+kaloko ci plan --dry-run --json        # show it, send nothing
+```
+
+Modes (Settings, per repository): `off`, `manual` (only after the label
+`kaloko:run` or the comment `/kaloko walk`), `auto` (the default) and
+`strict` (all scenarios, review required, unknown impact waits, the check
+times out after `wait_hours`). The `github:` section of `kaloko.config.yml`
+on the base branch may make it stricter, never looser:
+
+```yaml
+github:
+  checks: strict          # off | manual | auto | strict
+  scope: all              # affected | all
+  require_review: true
+  drafts: run             # wait (default) | run
+  skip_by: maintain       # write | maintain | admin
+  author_may_skip: false
+  wait_hours: 12
+```
+
+One pull request: the labels `kaloko:skip` (whole pull request), `kaloko:all`,
+`kaloko:review`, `kaloko:run`; the comments `/kaloko skip <reason>` (this
+commit only), `/kaloko walk`, `/kaloko all`; the buttons on the check. Only
+people with the access set in Settings skip, never apps or bots, and every
+skip is on the check and in the audit log. Do not skip a check yourself as an
+agent; walk, or tell the person why it fails.
+
+To make it block merging, the repository's branch protection (or ruleset)
+requires the status check `Kaloko`. Kaloko never changes branch protection.
+
+### Coding agents in the cloud
+
+An agent in a sandbox (Claude Code on the web, Codex, Cursor background
+agents, Copilot) runs the same commands as on a laptop:
+
+```bash
+git commit -am "…"                     # walk what is committed
+npx kaloko start --scenario qa/flows/checkout.yml --env preview
+npx kaloko walk --affected
+npx kaloko share                       # --pr also comments, if gh is signed in
+```
+
+- `KALOKO_TOKEN` goes into the sandbox's secrets or environment variables
+  (tester role, upload scope; a token per agent shows who shared what).
+- `npx kaloko browser install --with-deps` belongs in the environment's setup
+  script. When the sandbox cannot run a browser or reach the preview, let the
+  workflow above walk instead.
+- `gh` is not needed: the run carries the repository and the commit, and
+  Kaloko finds the pull request.
+
 ## Exit codes
 
 | Code | Meaning |

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'
@@ -126,6 +127,10 @@ Project
                                     In CI: the preview URL (KALOKO_PREVIEW_URL, the deployment event, provider
                                     variables or the commit's GitHub deployments), the pull request and its base;
                                     --wait polls that long for the deployment (seconds, or 10m)
+  ci plan [--scenario a.yml,b.yml] [--base ref] [--none] [--repo owner/name] [--sha commit] [--dry-run] [--json]
+                                    Tell the GitHub check which scenarios this commit reaches (kaloko affected, which
+                                    follows imports): it then waits for runs of those and passes for the rest;
+                                    --none marks the scenarios as not reached
   login [--org <slug>] [--url <service>] [--print] [--no-open]
                                     Sign this machine in through the browser: approve the code on kaloko.app, choose
                                     the organization and what the token may do; the token (at most 30 days) goes to
@@ -143,6 +148,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 +277,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 +321,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 +1266,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 +1288,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}`)
@@ -1767,7 +1780,31 @@ const commands = {
       console.log(preview.url)
       return
     }
-    if (!['github', 'gitlab'].includes(action)) throw new UsageError('Usage: kaloko ci github|gitlab [--scenario a.yml,b.yml] [--env preview] [--trigger deployment|pull_request] [--no-affected] [--out file] [--print] [--force]\n       kaloko ci github --release [--snippet] [--print] [--force]\n       kaloko ci preview-url [--wait 600] [--github-env] [--dotenv file]')
+    if (action === 'plan') {
+      // #141: what kaloko affected finds for this commit (it follows imports and affects: globs) decides the GitHub
+      // check over the service's guess from the file list; a scenario nothing reaches lets the check pass
+      const { config, root } = await context(args)
+      const g = await gitMeta(root)
+      const repo = typeof args.repo === 'string' ? args.repo : (g?.host === 'github' ? g.repo : null) || process.env.GITHUB_REPOSITORY || null
+      const sha = typeof args.sha === 'string' ? args.sha.toLowerCase() : g?.sha
+      if (!repo || !/^[\w.-]+\/[\w.-]+$/.test(repo)) throw new UserError('kaloko ci plan needs the GitHub repository: run it in a clone whose origin is on GitHub, or pass --repo owner/name.')
+      if (!sha || !/^[0-9a-f]{40}$/.test(sha)) throw new UserError('kaloko ci plan needs the full commit: run it inside the repository, or pass --sha.')
+      const targets = list(args.scenario)?.map((f) => resolve(f)) || await scenarioFiles(config, root)
+      if (!targets.length) throw new UserError('No scenario: pass --scenario <file> or list scenarios in the config.')
+      const scenarios = []
+      for (const file of targets) {
+        const scenario = await loadScenario(file)
+        if (args.none) { scenarios.push({ id: scenario.id, affected: false }); continue }
+        const r = await affectedSelection(args, { config, root, scenario, scenarioFile: file })
+        scenarios.push({ id: scenario.id, affected: !r.sel.none, steps: r.sel.none ? [] : selectedIds(scenario, r.sel) })
+      }
+      if (!args['dry-run']) await service(config).request('POST', `/orgs/${config.org}/github/plan`, { repo, sha, scenarios })
+      if (args.json) { say(JSON.stringify({ repo, sha, scenarios, sent: !args['dry-run'] }, null, 2)); return }
+      for (const x of scenarios) say(`${x.affected ? '→' : '·'} ${x.id}: ${x.affected ? `walk ${x.steps.length} step(s)` : 'nothing this change reaches'}`)
+      say(args['dry-run'] ? 'Not sent (--dry-run).' : `Sent to Kaloko for ${repo}@${sha.slice(0, 7)}: the GitHub check expects runs of the scenarios marked →.`)
+      return
+    }
+    if (!['github', 'gitlab'].includes(action)) throw new UsageError('Usage: kaloko ci github|gitlab [--scenario a.yml,b.yml] [--env preview] [--trigger deployment|pull_request] [--no-affected] [--out file] [--print] [--force]\n       kaloko ci github --release [--snippet] [--print] [--force]\n       kaloko ci preview-url [--wait 600] [--github-env] [--dotenv file]\n       kaloko ci plan [--scenario a.yml,b.yml] [--base ref] [--none] [--repo owner/name] [--sha commit] [--dry-run] [--json]')
     const { config, root, file } = await context(args)
     if (args.release) {
       // release-tool integrations: record each published release on Kaloko (docs/DOCS-CHANGELOG.md)
@@ -2330,7 +2367,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 +2382,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/changelog-core.mjs

@@ -60,11 +60,29 @@ export function formatStepRef ({ scenario = null, step, locale = null, viewport
 export function findStepRefs (markdown) {
   const out = []
   const re = /!\[([^\]]*)\]\((kaloko:[^)\s]+)\)/g
+  const text = withoutCode(String(markdown || ''))
   let m
-  while ((m = re.exec(String(markdown || '')))) out.push({ alt: m[1], ref: m[2], parsed: parseStepRef(m[2]), index: m.index })
+  while ((m = re.exec(text))) out.push({ alt: m[1], ref: m[2], parsed: parseStepRef(m[2]), index: m.index })
   return out
 }
 
+/** The Markdown with fenced code blocks and inline code blanked out (same length, newlines kept, so indexes still
+ *  point into the original): a reference shown as an example in a guide is text, not a picture to resolve. */
+export function withoutCode (md) {
+  const blank = (s) => s.replace(/[^\n]/g, ' ')
+  const lines = md.split('\n')
+  let fence = null
+  for (let i = 0; i < lines.length; i++) {
+    const f = lines[i].match(/^ {0,3}(?:[-*+]\s+|\d+[.)]\s+|>\s*)*(`{3,}|~{3,})/) || lines[i].match(/^\s*(`{3,}|~{3,})/)
+    if (fence) {
+      if (f && f[1][0] === fence[0] && f[1].length >= fence.length && !lines[i].trim().slice(f[1].length).trim()) fence = null
+      lines[i] = blank(lines[i])
+    } else if (f) { fence = f[1]; lines[i] = blank(lines[i]) }
+  }
+  // a code span stays inside its paragraph: a stray backtick never pairs across a blank line
+  return lines.join('\n').replace(/(?<!`)(`+)(?!`)(?:(?!\n[ \t]*\n)[\s\S])+?(?<!`)\1(?!`)/g, blank)
+}
+
 // ---------- versions ----------
 
 /** "v2.4.0" → "2.4.0"; anything else stays as it is (trimmed). */

package/src/lib/ci.mjs

@@ -99,9 +99,11 @@ export function runner ({ pm = 'npm', dependency = true, version = 'latest' }) {
 }
 
 /** The loop over scenarios both workflows run: walk what the change reaches, share, comment on the PR. */
-function walkScript ({ scenarios, env, affected, k }) {
+function walkScript ({ scenarios, env, affected, k, plan = false }) {
   return [
     'status=0',
+    // the Kaloko check on the pull request (GitHub App): which scenarios this commit reaches, followed through imports
+    ...(plan && affected ? [`${k} ci plan --scenario ${scenarios.map(q).join(',')} || echo "kaloko ci plan did not reach Kaloko; the GitHub check guesses from the changed files."`] : []),
     `for s in ${scenarios.map(q).join(' ')}; do`,
     ...(affected ? [`  if ! ${k} affected --scenario "$s" --fail-if-none; then echo "Nothing in $s is affected; skipped."; continue; fi`] : []),
     `  ${k} start --scenario "$s" --env ${env}`,
@@ -159,7 +161,7 @@ ${install ? `${['pnpm', 'yarn'].includes(pm) ? '      - run: corepack enable\n'
         run: ${k} ci preview-url --wait 600 --github-env
       - name: Walk, share, comment
         run: |
-${indent(walkScript({ scenarios, env, affected, k }), 10)}
+${indent(walkScript({ scenarios, env, affected, k, plan: true }), 10)}
 `
 }
 

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/git.mjs

@@ -90,5 +90,18 @@ export async function gitMeta (cwd) {
       pr = { number: p.number, url: p.url, state: String(p.state).toLowerCase(), ...(p.title ? { title: String(p.title).slice(0, 300) } : {}) }
     } catch {}
   }
-  return { branch: branch === 'HEAD' && ciBranch ? ciBranch : branch, commit, sha, message, author, pr }
+  // #141: the repository from the origin remote (a sandbox without gh has no PR; the service finds it by commit), the
+  // project's folder inside it (monorepos) and whether tracked files differ from the commit (such a walk does not
+  // count for the commit's GitHub check)
+  const [origin, prefix, changes] = await Promise.all([
+    repoSlug(cwd),
+    out('git', ['rev-parse', '--show-prefix'], cwd),
+    out('git', ['status', '--porcelain', '--untracked-files=no'], cwd)
+  ])
+  return {
+    branch: branch === 'HEAD' && ciBranch ? ciBranch : branch, commit, sha, message, author, pr,
+    ...(origin ? { repo: origin.slug, host: origin.host } : {}),
+    ...(prefix ? { prefix: prefix.replace(/\/$/, '') } : {}),
+    dirty: changes === null ? false : changes.length > 0
+  }
 }

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(); }
@@ -3945,7 +3973,13 @@ function applyHash () {
 }
 
 /* ---------- replay: guided walkthrough with branch choice ---------- */
-const outEdges = (id) => RUN.edges.filter((e) => e.from === id && byId(e.to)).sort((a, b) => (a.kind === 'alt') - (b.kind === 'alt'));
+// the ways on from a step in the order of the map: the main path before alternatives, forward before back, the same
+// row before another, then the nearest column and row, so → in replay follows the diagram, not the order of the file
+const outEdges = (id) => {
+  const from = byId(id); const c = (n) => n?.col || 0, l = (n) => n?.lane || 0;
+  const k = (e) => { const t = byId(e.to); return [e.kind === 'alt' ? 1 : 0, c(t) > c(from) ? 0 : 1, l(t) === l(from) ? 0 : 1, Math.abs(c(t) - c(from)), Math.abs(l(t) - l(from))]; };
+  return RUN.edges.filter((e) => e.from === id && byId(e.to)).map((e, i) => [e, k(e), i]).sort(([, a, i], [, b, j]) => { for (let x = 0; x < a.length; x++) if (a[x] !== b[x]) return a[x] - b[x]; return i - j; }).map(([e]) => e);
+};
 function startNode () { const order = RUN.nodes.slice().sort((a, b) => a.col - b.col || a.lane - b.lane); return order.find((n) => !RUN.edges.some((e) => e.to === n.id)) || order[0]; }
 function rpOpen (path) {
   const ids = (path || []).filter((id) => byId(id));
@@ -4007,7 +4041,8 @@ function renderReplay () {
   $('rpClose').onclick = rpClose; $('rpPrev').onclick = rpBack;
   $('rp').querySelectorAll('[data-go]').forEach((b) => { b.onclick = () => rpGo(b.dataset.go); });
   $('rp').querySelectorAll('[data-jump]').forEach((b) => { b.onclick = () => rpJump(Number(b.dataset.jump)); });
-  $('rp').querySelectorAll('[data-stack-open]').forEach((b) => { b.onclick = () => openStack(b.dataset.stackOpen); });
+  // the stack's index opens over the canvas, not under the replay (which would hide it and take its keys)
+  $('rp').querySelectorAll('[data-stack-open]').forEach((b) => { b.onclick = () => { const id = b.dataset.stackOpen; rpClose(); openStack(id); }; });
   $('rp').querySelector('[data-restart]')?.addEventListener('click', () => rpOpen(null));
   if ($('rpVid')) $('rpVid').onclick = () => { S.rpVideo = !S.rpVideo; renderReplay(); };
   if (S.rpVideo) {
@@ -5554,6 +5589,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',