kaloko 0.7.1 → 0.9.0

package/src/lib/doctor.mjs

@@ -2,8 +2,10 @@
 // Every check returns { name, ok, detail, hint } so the CLI and tests can read it.
 import { appTools, macPermissions } from './apps/drivers.mjs'
 import { createServer } from 'node:net'
-import { access as exists, stat } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { access as exists, stat, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { resolve, join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawn } from 'node:child_process'
 import { environment } from './config.mjs'
 import { gateOf, gateHeaders, accountFor } from './access.mjs'
 import { missing } from './secrets.mjs'
@@ -38,21 +40,38 @@ async function reach (url, fetchImpl, ms = 6000, headers = {}) {
  * @param {Function} [o.launchEngine] async (engine) => { version } — throws when the engine is not installed
  * @param {object} [o.tools] app tools found (default: looked up on PATH)
  * @param {object[]} [o.scenarios] { file, product, module } of the scenario files (products checks)
+ * @param {boolean} [o.fix] repair what can be repaired here: install missing Playwright browsers, create the run and
+ *   scenario folders, write org: from the token into the config, ask macOS for permissions
+ * @param {Function} [o.installBrowser] async (engine) => void — installs a Playwright engine (--fix)
  */
-export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false, engines = null, launchEngine = defaultEngine, tools = null, os = process.platform, videoToolsImpl = null, scenarios = [] }) {
+export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false, engines = null, launchEngine = defaultEngine, tools = null, os = process.platform, videoToolsImpl = null, scenarios = [], installBrowser = defaultInstall }) {
   const checks = []
-  const add = (name, ok, detail = '', hint = '') => checks.push({ name, ok, detail, hint })
+  const add = (name, ok, detail = '', hint = '', fixed = null) => checks.push({ name, ok, detail, hint, ...(fixed ? { fixed } : {}) })
+  // --fix: install an engine, then look again; returns the version or throws what the install said
+  const installed = async (engine, retry) => { await installBrowser(engine); return retry() }
 
   const major = Number(process.versions.node.split('.')[0])
   add('node', major >= 20, `Node ${process.versions.node}`, major >= 20 ? '' : 'Kaloko needs Node 20 or newer.')
 
   add('config', true, `${file || `${root}/kaloko.config.yml`} · org ${config.org || '—'} · ${Object.keys(config.environments || {}).length} environments`)
-  if (!config.org) add('org', false, 'no org in config', 'Set org: <slug> (the organization slug from kaloko.app).')
+  if (!config.org) add('org', false, 'no org in config', 'Set org: <slug> (the part after kaloko.app/ when you are signed in), or run kaloko doctor --fix with a token to fill it in.')
+  await folderChecks({ config, root, fix, add })
 
-  try { const c = await launchChrome(config); add('chrome', true, c.version ? `Chrome ${c.version}` : 'Chrome found') } catch (e) { add('chrome', false, e.message.split('\n')[0].slice(0, 160), config.browser?.channel ? 'Install Google Chrome, or remove browser.channel to use bundled Chromium (npx playwright install chromium).' : 'Run: npx playwright install chromium') }
+  try { const c = await launchChrome(config); add('chrome', true, c.version ? `Chrome ${c.version}` : 'Chrome found') } catch (e) {
+    let done = null
+    // the bundled Chromium can be installed from here; a branded Chrome (browser.channel) is the person's to install
+    if (fix && !config.browser?.channel) { try { done = await installed('chromium', () => launchChrome(config)) } catch {} }
+    if (done) add('chrome', true, `Chromium ${done.version || ''}`.trim(), '', 'installed Chromium for Playwright')
+    else add('chrome', false, e.message.split('\n')[0].slice(0, 160), config.browser?.channel ? 'Install Google Chrome, or remove browser.channel to use bundled Chromium (kaloko browser install).' : fix ? 'Installing Chromium did not work; run kaloko browser install and read its output (on Linux add --with-deps).' : 'Run kaloko doctor --fix (or kaloko browser install) to install Chromium for Playwright.')
+  }
   // cross-browser runs (batch E): the Playwright engines the scenarios and walk.browsers name
   for (const engine of [...new Set([...(engines || []), ...(config.walk?.browsers || [])])].filter((e) => e !== 'chromium')) {
-    try { const v = await launchEngine(engine); add(`browser ${engine}`, true, `${engine} ${v.version || ''}`.trim()) } catch { add(`browser ${engine}`, false, `${engine} is not installed for Playwright`, `Run: kaloko browser install --browsers ${engine}${os === 'linux' ? ' --with-deps' : ''}`) }
+    try { const v = await launchEngine(engine); add(`browser ${engine}`, true, `${engine} ${v.version || ''}`.trim()) } catch {
+      let done = null
+      if (fix) { try { done = await installed(engine, () => launchEngine(engine)) } catch {} }
+      if (done) add(`browser ${engine}`, true, `${engine} ${done.version || ''}`.trim(), '', `installed ${engine} for Playwright`)
+      else add(`browser ${engine}`, false, `${engine} is not installed for Playwright`, `Run kaloko doctor --fix, or kaloko browser install --browsers ${engine}${os === 'linux' ? ' --with-deps' : ''}`)
+    }
   }
 
   for (const name of Object.keys(config.environments || {})) {
@@ -132,16 +151,21 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
   else {
     try {
       const res = await fetchImpl(`${service}/api/v1/me`, { headers: { Authorization: `Bearer ${token}` } })
-      if (!res.ok) add('token', false, `${service} → HTTP ${res.status}`, res.status === 401 ? `${tokenEnv} is invalid, expired or revoked; create a new one in Settings.` : 'The service did not accept the request.')
+      if (!res.ok) add('token', false, `${service} → HTTP ${res.status}`, res.status === 401 ? `${tokenEnv} is invalid, expired or revoked. Run kaloko login for a new one (it replaces the old token), or create one in Settings → API tokens.` : `The service did not accept the request; try again in a few minutes (${service}/status).`)
       else {
         const me = await res.json()
+        // --fix: a config without org: takes the token's organization
+        if (!config.org && fix && me.org && file) {
+          const wrote = await writeOrg(file, me.org).catch(() => false)
+          if (wrote) { config.org = me.org; const i = checks.findIndex((c) => c.name === 'org'); if (i >= 0) checks[i] = { name: 'org', ok: true, detail: `org ${me.org}`, hint: '', fixed: `wrote org: ${me.org} into ${file}` } }
+        }
         const sameOrg = !config.org || me.org === config.org
         // sharing runs needs the Developer / Tester role (or admin) and, on tokens with scope sets, the upload scope
         const canShare = ['tester', 'admin'].includes(me.role) && (!Array.isArray(me.scopes) || me.scopes.includes('upload'))
         add('token', sameOrg, `${me.email} · ${me.role} · org ${me.org}${canShare ? '' : ' (this token cannot share runs)'}`, sameOrg ? '' : `The token belongs to organization "${me.org}" but the config says "${config.org}".`)
         if (!canShare) add('token role', false, Array.isArray(me.scopes) ? `${me.role} · ${me.scopes.join(', ')}` : me.role, 'kaloko share needs a Developer / Tester token with the upload scope.')
       }
-    } catch (e) { add('token', false, `${service} unreachable: ${e.message}`, 'Check your network; KALOKO_URL overrides the service URL.') }
+    } catch (e) { add('token', false, `${service} unreachable: ${e.cause?.code || e.message}`, 'Check your network or VPN; KALOKO_URL points the CLI to another service.') }
   }
 
   const jev = config.evaluators?.jev
@@ -173,6 +197,44 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
   return { ok: checks.every((c) => c.ok), checks }
 }
 
+/** The run folder and the folders the scenario globs start in: reported, and created with --fix. */
+async function folderChecks ({ config, root, fix, add }) {
+  const there = (d) => exists(d).then(() => true, () => false)
+  const out = resolve(root, config.output || 'tmp/kaloko')
+  if (!await there(out)) {
+    if (fix && await mkdir(out, { recursive: true }).then(() => true, () => false)) add('folders', true, `${config.output} created`, '', `created ${config.output}`)
+  }
+  for (const pattern of config.scenarios || []) {
+    const fixed = []
+    for (const p of pattern.split('/')) { if (/[*?{[]/.test(p)) break; fixed.push(p) }
+    if (!fixed.length || fixed.length === pattern.split('/').length) continue
+    const dir = resolve(root, ...fixed)
+    if (await there(dir)) continue
+    if (fix && await mkdir(dir, { recursive: true }).then(() => true, () => false)) add(`scenarios ${fixed.join('/')}`, true, 'folder created; it has no scenarios yet', 'Draft a first one: kaloko draft <url>', `created ${fixed.join('/')}`)
+    else add(`scenarios ${fixed.join('/')}`, false, `${fixed.join('/')} does not exist (scenarios: ${pattern})`, 'Run kaloko doctor --fix to create it, then kaloko draft <url> for a first scenario.')
+  }
+}
+
+/** Writes org: <slug> into the config file, keeping its comments and layout. */
+export async function writeOrg (file, org) {
+  if (!/^[a-z0-9-]+$/.test(org)) return false
+  const text = await readFile(file, 'utf8')
+  let next
+  if (/^org:.*$/m.test(text)) next = text.replace(/^org:.*$/m, `org: ${org}`)
+  else if (/^schema:.*$/m.test(text)) next = text.replace(/^(schema:.*)$/m, `$1\norg: ${org}`)
+  else next = `org: ${org}\n${text}`
+  if (next === text) return false
+  await writeFile(file, next)
+  return true
+}
+
+/** Installs a Playwright engine with the Playwright that kaloko itself uses (same as kaloko browser install). */
+async function defaultInstall (engine) {
+  const cli = join(dirname(fileURLToPath(import.meta.resolve('playwright/package.json'))), 'cli.js')
+  const code = await new Promise((done) => spawn(process.execPath, [cli, 'install', engine], { stdio: 'inherit' }).on('close', done).on('error', () => done(1)))
+  if (code) throw new Error(`playwright install ${engine} exited with ${code}`)
+}
+
 async function defaultEngine (engine) {
   const pw = await import('playwright')
   const browser = await pw[engine].launch({ headless: true })
@@ -189,4 +251,4 @@ async function defaultLaunch (config) {
   return { version }
 }
 
-export const formatDoctor = ({ ok, checks }) => [...checks.map((c) => `${c.ok ? '✓' : '✕'} ${c.name.padEnd(16)} ${c.detail}${!c.ok && c.hint ? `\n    → ${c.hint}` : ''}`), ok ? 'All good.' : 'Fix the ✕ items above.'].join('\n')
+export const formatDoctor = ({ ok, checks }) => [...checks.map((c) => `${c.ok ? '✓' : '✕'} ${c.name.padEnd(16)} ${c.detail}${c.fixed ? ` (fixed: ${c.fixed})` : ''}${(!c.ok || c.fixed) && c.hint ? `\n    → ${c.hint}` : ''}`), ok ? 'All good.' : checks.some((c) => !c.ok && /doctor --fix/.test(c.hint || '')) ? 'Fix the ✕ items above; kaloko doctor --fix repairs the ones that say so.' : 'Fix the ✕ items above.'].join('\n')

package/src/lib/evaluate.mjs

@@ -17,6 +17,8 @@ export function latestCaptures (entries) {
 }
 
 export const criteriaHash = (node) => sha256(node.criteria || [])
+/** A criterion with `environments` (e.g. [production]) applies only there; without a known environment it applies. */
+export const appliesOn = (c, environment) => !environment || !Array.isArray(c.environments) || !c.environments.length || c.environments.includes(environment)
 /** Folder of a capture under steps/: the node, or steps/<node>/items/<item> for a page of a stack step. */
 export const stepIdOf = (e) => (e.item ? `${e.node}/items/${e.item}` : e.node)
 export const evaluationSource = (node, capture) => sha256({ capture, criteria: node.criteria || [], purpose: node.purpose || '' })
@@ -26,8 +28,9 @@ export const evaluationSource = (node, capture) => sha256({ capture, criteria: n
  * asked, the vision evaluator. Every semantic verdict with a score carries a one-sentence `reason`: the vision
  * model's own, or a sentence saying what the text evaluator read (it returns a probability only).
  */
-export function combine ({ node, capture, jev, vision = null, thresholds }) {
+export function combine ({ node, capture, jev, vision = null, thresholds, environment = null }) {
   return (node.criteria || []).map((c) => {
+    if (!appliesOn(c, environment)) return { id: c.id, type: c.check.type, verdict: 'not_evaluated', evidence: `Applies on ${c.environments.join(', ')} only; this walk ran on ${environment}.`, na: true, not_applicable: 'environment' }
     if (c.check.type === 'deterministic') {
       const r = capture.checks?.[c.id]
       const verdict = r == null || r.ok == null ? 'not_evaluated' : r.ok ? 'pass' : 'fail'
@@ -64,6 +67,8 @@ export async function evaluateRun ({ run, scenario, config, root, fetchImpl }) {
   const cacheDir = join(resolve(root, config.output), '.cache', 'jev')
   const nodes = new Map(scenario.nodes.map((n) => [n.id, n]))
   const paths = runPaths(run.dir)
+  // criteria limited to other environments (environments: [production]) are reported as not applicable here
+  const environment = run.meta?.environment?.name || null
   const report = { evaluated: 0, semantic_calls: 0, semantic_cached: 0, skipped: [], model: settings.model, drift: 0, outdated: new Set(), via: {}, hosted: null, hostedStop: null, findings: [] }
   // the vision evaluator (#17): flagged and uncertain criteria, a bounded number of calls per evaluation
   const vset = visionSettings(config)
@@ -101,7 +106,7 @@ export async function evaluateRun ({ run, scenario, config, root, fetchImpl }) {
       const current = capture.criteria_hash === criteriaHash(node)
       // console triage needs the evaluator only when the capture has console errors
       const outOfSample = entry.item && !sampled.get(entry.node)?.has(entry.item)
-      const semantic = outOfSample ? [] : (node.criteria || []).filter((c) => c.check.type === 'semantic' && !(c.check.about === 'console' && !(capture.console_errors || []).length))
+      const semantic = outOfSample ? [] : (node.criteria || []).filter((c) => c.check.type === 'semantic' && appliesOn(c, environment) && !(c.check.about === 'console' && !(capture.console_errors || []).length))
       // quick signals ride along on every captured page state (also steps without semantic criteria)
       const signals = settings.signals !== false && !outOfSample && !!capture.state
       // an imported screen without page text (#11) has nothing to ask about: a person decides on the canvas
@@ -126,7 +131,7 @@ export async function evaluateRun ({ run, scenario, config, root, fetchImpl }) {
       const source = evaluationSource(node, capture)
       if (drift && current && needsDrift(node)) { capture.checks = { ...capture.checks, ...await driftForCapture({ node, entry, capture, runDir: run.dir, ctx: drift }) }; report.drift++ }
       if (styleTokens?.tokens && current && tokenCriteria(node).length) capture.checks = { ...capture.checks, ...storedValueChecks(node, capture, { ...styleTokens, recorded: !!capture.rechecked_at, only: (c) => !!c.check.token && STYLE_ASSERTS.has(c.check.assert) }) }
-      let criteria = combine({ node, capture: current ? capture : {}, jev, vision: seen, thresholds: settings.thresholds })
+      let criteria = combine({ node, capture: current ? capture : {}, jev, vision: seen, thresholds: settings.thresholds, environment })
       // pages outside the semantic sample carry only the deterministic results
       if (outOfSample) criteria = criteria.filter((c) => c.type !== 'semantic' || c.evidence === 'no console errors')
       const evaluation = {
@@ -175,7 +180,7 @@ function signalsOf (jev) {
   return Object.keys(out).length ? out : null
 }
 
-export function semanticPrefetch ({ scenario, config, root }) {
+export function semanticPrefetch ({ scenario, config, root, environment = null }) {
   const settings = { ...DEFAULTS, ...(config.evaluators?.jev || {}), thresholds: { ...DEFAULTS.thresholds, ...(config.evaluators?.jev?.thresholds || {}) } }
   const cacheDir = join(resolve(root, config.output), '.cache', 'jev')
   const nodes = new Map(scenario.nodes.map((n) => [n.id, n]))
@@ -197,7 +202,7 @@ export function semanticPrefetch ({ scenario, config, root }) {
       for (const e of [].concat(entries || [])) {
         if (e?.type !== 'capture' || e.item) continue
         const node = nodes.get(e.node)
-        const semantic = (node?.criteria || []).filter((c) => c.check.type === 'semantic')
+        const semantic = (node?.criteria || []).filter((c) => c.check.type === 'semantic' && appliesOn(c, environment))
         if (!semantic.length && settings.signals === false) continue
         queue.push(async () => {
           const capture = await readJson(join(runDir, e.file))
@@ -283,7 +288,7 @@ function hostedSender (config, report) {
     try { if (!client) { const { service } = await import('./service.mjs'); client = service(config) } } catch { return { skipped: 'no evaluator key (TYPESAFE_API_KEY) and no service token (KALOKO_TOKEN) for hosted evaluation' } }
     try { return { response: await client.request('POST', `/orgs/${config.org}/semantic`, JSON.parse(body)) } } catch (e) {
       const m = String(e.message || e)
-      if (/HTTP (402|403|503)/.test(m)) { report.hostedStop = m.replace(/^.*HTTP \d+: /, ''); return { skipped: report.hostedStop } }
+      if (/HTTP (402|403|503)/.test(m)) { report.hostedStop = e.serviceMessage ?? m.replace(/^.*HTTP \d+: /, ''); return { skipped: report.hostedStop } }
       return { error: m }
     }
   }

package/src/lib/figma.mjs

@@ -63,7 +63,7 @@ export function figmaClient ({ token, fetch: f = globalThis.fetch, base = figmaA
     variables: (key) => get(`/v1/files/${key}/variables/local`, { optional: true }),
     async download (url) {
       const res = await f(url)
-      if (!res.ok) throw new UserError(`Downloading a frame image failed: HTTP ${res.status}.`)
+      if (!res.ok) throw new UserError(`Downloading a frame image from Figma failed (HTTP ${res.status}). Figma's image links expire after a while; run the import again.`)
       return Buffer.from(await res.arrayBuffer())
     }
   }

package/src/lib/integrations-cli.mjs

@@ -4,7 +4,7 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { resolve, relative, dirname, join } from 'node:path'
-import { UserError } from './util.mjs'
+import { UserError, NO_ORG } from './util.mjs'
 import { gateOf, accountFor } from './access.mjs'
 import { secret } from './secrets.mjs'
 import { runner } from './ci.mjs'
@@ -23,7 +23,7 @@ const issueLine = (i) => `${i.key.padEnd(10)} ${String(i.state).padEnd(8)} step
 export async function issueCmd ({ args, config, client, runId, say }) {
   const sub = args._[0]
   const org = config.org
-  if (!org) throw new UserError('Set org: in the config first.')
+  if (!org) throw new UserError(NO_ORG)
   if (sub === 'list') {
     const q = new URLSearchParams(Object.entries({ run: typeof args.run === 'string' ? args.run : null, scenario: typeof args.scenario === 'string' ? args.scenario : null, state: typeof args.state === 'string' ? args.state : null }).filter(([, v]) => v))
     const items = await client.request('GET', `/orgs/${org}/issues${q.size ? `?${q}` : ''}`)
@@ -169,7 +169,7 @@ export async function scheduleCmd ({ args, config, root, say, deps }) {
     say(`Wrote ${relative(process.cwd(), out)}: ${scenario.id} on ${envName} ${every === 'week' ? 'every week' : 'every day'} at ${String(atHour(args.at)).padStart(2, '0')}:00 UTC with the full walk (clicks, forms, every criterion).\nNext: add the repository secret KALOKO_TOKEN${secretNames(env, scenario).length ? ` and ${secretNames(env, scenario).join(', ')}` : ''}, then commit the workflow.`)
     return { file: out }
   }
-  if (!org) throw new UserError('Set org: in the config first.')
+  if (!org) throw new UserError(NO_ORG)
   if (sub === 'list' || !sub) {
     const data = await client().request('GET', `/orgs/${org}/schedules`)
     if (args.json) { say(JSON.stringify(data, null, 2)); return data }

package/src/lib/login.mjs

@@ -34,7 +34,7 @@ export async function login (base, { org = null, print = false, open = true, tok
   base = base.replace(/\/$/, '')
   const post = async (path, body) => {
     let res
-    try { res = await fetchImpl(`${base}${path}`, { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify(body) }) } catch (e) { throw new UserError(`Cannot reach ${base}: ${e.message}`) }
+    try { res = await fetchImpl(`${base}${path}`, { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify(body) }) } catch (e) { throw new UserError(`Cannot reach ${base} (${e.cause?.code || e.message}). Check your network or VPN and run kaloko login again; --url or KALOKO_URL points it to another service.`) }
     return { status: res.status, body: await res.json().catch(() => ({})) }
   }
   const start = await post('/cli/device', { client: `kaloko${version ? ` ${version}` : ''} on ${hostname()}`.slice(0, 60) })

package/src/lib/mail.mjs

@@ -13,7 +13,7 @@ const address = (a) => (a?.Address ? (a.Name ? `${a.Name} <${a.Address}>` : a.Ad
 
 /** Mailpit REST client (https://mailpit.axllent.org/docs/api-v1/). */
 export function mailpit (mail) {
-  if (!mail || mail.provider !== 'mailpit' || !mail.url) throw new UserError('Environment has no mail.provider: mailpit with url.')
+  if (!mail || mail.provider !== 'mailpit' || !mail.url) throw new UserError('This environment has no Mailpit mailbox. Add mail: { provider: mailpit, url: <Mailpit address> } to it in kaloko.config.yml.')
   const headers = {}
   // `auth.basic` (older configs: user_env / password_env next to url), plus any headers of a gate in front of it
   const basic = mail.auth?.basic || (mail.user_env ? { user_env: mail.user_env, password_env: mail.password_env } : null)

package/src/lib/manifest-core.mjs

@@ -99,24 +99,29 @@ export function assembleNode ({ node, pos, locales, viewportNames, captures, att
       // semantic answers carry the thresholds they were judged by and where they were evaluated (own key or Kaloko)
       // semantic answers carry their one-sentence reason (#17) and whether the evaluator saw the screenshot
       const seen = r.provider && /-vision$/.test(r.provider)
-      loc[c.viewport] = { verdict: r.verdict, evidence: r.evidence, score, note: r.note ?? null, ...(r.na ? { na: true } : {}), ...(score != null && ev.thresholds ? { th: [ev.thresholds.fail, ev.thresholds.pass] } : {}), ...(r.type === 'semantic' && (seen ? ev.vision?.via : ev.semantic?.via) ? { via: seen ? ev.vision.via : ev.semantic.via } : {}), ...(r.reason ? { reason: r.reason, ...(r.reason_source === 'model' ? { reason_by: 'model' } : {}) } : {}), ...(seen ? { vision: true, ...(r.text_score != null ? { text_score: r.text_score } : {}) } : {}) }
+      loc[c.viewport] = { verdict: r.verdict, evidence: r.evidence, score, note: r.note ?? null, ...(r.na ? { na: true } : {}), ...(r.not_applicable ? { not_applicable: r.not_applicable } : {}), ...(score != null && ev.thresholds ? { th: [ev.thresholds.fail, ev.thresholds.pass] } : {}), ...(r.type === 'semantic' && (seen ? ev.vision?.via : ev.semantic?.via) ? { via: seen ? ev.vision.via : ev.semantic.via } : {}), ...(r.reason ? { reason: r.reason, ...(r.reason_source === 'model' ? { reason_by: 'model' } : {}) } : {}), ...(seen ? { vision: true, ...(r.text_score != null ? { text_score: r.text_score } : {}) } : {}) }
       if (r.evidence && (!agg.evidence || r.verdict !== 'pass')) agg.evidence = r.evidence
       if (r.reason && (!agg.reason || (r.verdict !== 'pass' && agg.reason_verdict === 'pass'))) { agg.reason = r.reason; agg.reason_verdict = r.verdict }
     }
   }
   const criteria = [...perCriterion.values()].map(({ reason_verdict: _rv, ...agg }) => {
     for (const l of applicable) for (const vp of viewportNames) ((agg.by_locale[l] ||= {})[vp] ||= { verdict: 'not_reached' })
-    const verdicts = counted(applicable.flatMap((l) => viewportNames.map((vp) => agg.by_locale[l][vp])))
-    return { ...agg, verdict: aggregate(verdicts) }
+    const entries = applicable.flatMap((l) => viewportNames.map((vp) => agg.by_locale[l][vp]))
+    const verdicts = counted(entries)
+    // a criterion limited to other environments (environments: [production]) is not applicable on this walk:
+    // reported as such, and it does not make the step partial
+    const offEnv = entries.some((e) => e.not_applicable) && entries.every((e) => e.not_applicable || e.verdict === 'not_reached')
+    return { ...agg, verdict: aggregate(verdicts), ...(offEnv ? { not_applicable: 'environment' } : {}) }
   })
+  const counting = criteria.filter((c) => !c.not_applicable)
   const byLocale = {}
   for (const l of locales) {
     const captured = !!capturesOut[l]
-    const vs = criteria.map((c) => aggregate(counted(Object.values(c.by_locale[l] || {}))))
+    const vs = counting.map((c) => aggregate(counted(Object.values(c.by_locale[l] || {}))))
     if (applicable.includes(l) && viewportNames.some((vp) => !capturesOut[l]?.[vp])) vs.push('not_reached')
     byLocale[l] = statusOf(vs, captured)
   }
-  const verdicts = criteria.map((c) => c.verdict)
+  const verdicts = counting.map((c) => c.verdict)
   if (applicable.some((l) => viewportNames.some((vp) => !capturesOut[l]?.[vp]))) verdicts.push('not_reached')
   return {
     ...base,
@@ -137,7 +142,7 @@ export function summarize (nodes, sessions = null) {
   const screens = nodes.filter((n) => n.kind !== 'decision')
   const summary = { pass: 0, partial: 0, fail: 0, skip: 0, criteria: {} }
   for (const n of screens) summary[n.status]++
-  for (const n of screens) for (const c of n.criteria) summary.criteria[c.verdict] = (summary.criteria[c.verdict] || 0) + 1
+  for (const n of screens) for (const c of n.criteria) if (!c.not_applicable) summary.criteria[c.verdict] = (summary.criteria[c.verdict] || 0) + 1
   if (sessions) {
     summary.by_session = {}
     for (const key of Object.keys(sessions)) summary.by_session[key] = { pass: 0, partial: 0, fail: 0, skip: 0 }

package/src/lib/pack-help.mjs

@@ -18,6 +18,11 @@ export const PACK_HELP = {
   AC202: { cs: 'Jedna jasná hlavní akce', why: ['Several equally loud buttons make people hesitate; none leaves them without a next step.', 'Několik stejně výrazných tlačítek lidi zdrží; žádné je nechá bez dalšího kroku.'], fix: ['Give one action the primary style; make the others secondary or links.', 'Jedné akci dejte hlavní styl, ostatní udělejte vedlejší nebo jako odkazy.'] },
   AC203: { cs: 'Formulářová pole mají viditelný popisek', why: ['A placeholder disappears as people type; they forget what the field was.', 'Placeholder při psaní zmizí a lidé zapomenou, co do pole patří.'], fix: ['Add a <label for="…"> (or aria-label) to every visible input.', 'Ke každému viditelnému poli doplňte <label for="…"> (nebo aria-label).'] },
   AC204: { cs: 'Odkazy a tlačítka říkají, co udělají', why: ['"Click here" or "More" does not say where it leads, especially out of context or to a screen reader.', '„Klikněte zde“ nebo „Více“ neřekne, kam vede, zvlášť mimo kontext nebo ve čtečce.'], fix: ['Name the result: "Download the price list", "Continue to payment".', 'Pojmenujte výsledek: „Stáhnout ceník“, „Pokračovat k platbě“.'] },
+  AC205: { cs: 'Z nadpisu je jasné, k čemu obrazovka je', why: ['People switch between screens all day; a vague heading makes them check where they are.', 'Lidé mezi obrazovkami přepínají celý den; s mlhavým nadpisem musí hledat, kde vlastně jsou.'], fix: ['Name the screen after what it shows or does: "Runs of the checkout flow", not "Dashboard".', 'Pojmenujte obrazovku podle toho, co ukazuje nebo dělá: „Běhy flow pokladny“, ne „Nástěnka“.'] },
+  AC206: { cs: 'Je jasné, jak formulář odeslat a co bude dál', why: ['When the send button or the next step is unclear, people submit twice or give up.', 'Když není jasné odesílací tlačítko nebo další krok, lidé odešlou dvakrát nebo to vzdají.'], fix: ['Label the button with the result ("Send the link") and say in one sentence what happens next.', 'Tlačítko pojmenujte podle výsledku („Poslat odkaz“) a jednou větou řekněte, co bude dál.'] },
+  AC207: { cs: 'Každá položka seznamu říká, co je zač a jak ji otevřít', why: ['A row with only an id or a date makes people open items one by one to find the right one.', 'Řádek jen s identifikátorem nebo datem nutí lidi otevírat položky jednu po druhé.'], fix: ['Show a name and a state in every row and make the name the link.', 'V každém řádku ukažte název a stav a z názvu udělejte odkaz.'] },
+  AC208: { cs: 'Každé nastavení říká, co změní a jak se uloží', why: ['People leave settings unsure whether the change took effect.', 'Lidé odcházejí z nastavení a nevědí, jestli se změna projevila.'], fix: ['Add a short hint under each setting and either a save button or a visible "Saved".', 'Pod každé nastavení přidejte krátkou nápovědu a buď tlačítko Uložit, nebo viditelné „Uloženo“.'] },
+  AC209: { cs: 'Text jde rychle projít: nadpisy a krátké odstavce', why: ['Readers of documentation scan for their question; a wall of text hides the answer.', 'Čtenář dokumentace hledá svou otázku očima; souvislý text odpověď schová.'], fix: ['Split the text under headings that name the question and keep paragraphs to a few sentences.', 'Rozdělte text pod nadpisy, které pojmenují otázku, a odstavce držte na pár větách.'] },
   AC301: { cs: 'Obrázky mají alternativní text', why: ['Without alt text, blind visitors and search engines do not know what an image shows.', 'Bez alt textu nevidomí ani vyhledávače nevědí, co obrázek ukazuje.'], fix: ['Add alt="…" describing the image; decorative images get alt="".', 'Doplňte alt="…" s popisem obrázku; dekorativní obrázky dostanou alt="".'] },
   AC302: { cs: 'Odkazy a tlačítka mají přístupný název', why: ['An icon button without a name is read as just "button".', 'Tlačítko s ikonou bez názvu čtečka přečte jen jako „tlačítko“.'], fix: ['Add visible text or aria-label to icon-only links and buttons.', 'Odkazům a tlačítkům jen s ikonou doplňte text nebo aria-label.'] },
   AC303: { cs: 'Formulářová pole mají popisky', why: ['Screen reader users hear only "edit text" for a field without a label.', 'Uživatel čtečky uslyší u pole bez popisku jen „editační pole“.'], fix: ['Connect a <label> to each field (for/id) or use aria-label / aria-labelledby.', 'Ke každému poli připojte <label> (for/id) nebo použijte aria-label / aria-labelledby.'] },

package/src/lib/packs.mjs

@@ -33,13 +33,23 @@ export const PACKS = {
   },
   usability: {
     base: 200,
-    title: 'Usability: purpose, primary action, forms, feedback',
-    criteria: () => [
-      { id: 'AC201', text: 'The purpose of the page is clear within the first screen', check: { type: 'semantic', question: 'Is the purpose of this page clear from its heading and first paragraph alone?', scope: 'main, body' } },
-      { id: 'AC202', text: 'One clear primary action', check: { type: 'semantic', question: 'Is there exactly one clearly primary call to action on the page?', scope: 'main, body' } },
-      { id: 'AC203', text: 'Form fields have visible labels', check: det('count', { selector: 'input:not([type=hidden]):not([type=submit]):not([aria-label]):not([id])', min: 0, max: 0 }) },
-      { id: 'AC204', text: 'Links and buttons say what they do', check: { type: 'semantic', question: 'Do the link and button texts describe what happens when they are used, rather than generic words like "click here"?', scope: 'main, body' } }
-    ]
+    title: 'Usability by page type (`page` on the step or scenario): purpose, a primary action on landing pages, forms, lists, settings, link texts',
+    criteria: ({ page = 'landing' } = {}) => {
+      const sem = (question) => ({ type: 'semantic', question, scope: 'main, body' })
+      const on = (...types) => types.includes(page)
+      return [
+        ...(on('landing', 'doc') ? [{ id: 'AC201', text: 'The purpose of the page is clear within the first screen', check: sem('Is the purpose of this page clear from its heading and first paragraph alone?') }] : []),
+        ...(on('work', 'list', 'settings', 'form') ? [{ id: 'AC205', text: 'The heading says what the screen is for', check: sem('Is it clear from the heading and the content of this screen what it is for?') }] : []),
+        // one loud call to action is a landing-page rule; work screens, lists and settings rightly offer several actions
+        ...(on('landing') ? [{ id: 'AC202', text: 'One clear primary action', check: sem('Is there exactly one clearly primary call to action on the page?') }] : []),
+        ...(on('form') ? [{ id: 'AC206', text: 'It is clear how to send the form and what happens next', check: sem('Is it clear which button sends the form and what happens after it is sent?') }] : []),
+        ...(on('list') ? [{ id: 'AC207', text: 'Each item in the list says what it is and how to open it', check: sem('Does each item in the list show what it is (for example a name and its state) and how to open it?') }] : []),
+        ...(on('settings') ? [{ id: 'AC208', text: 'Each setting says what it changes and how it is saved', check: sem('Does each setting say what it changes, and is it clear whether a change is saved by itself or with a button?') }] : []),
+        ...(on('doc') ? [{ id: 'AC209', text: 'The text can be scanned: headings and short paragraphs', check: sem('Is the text split into headings and short paragraphs that a reader can scan?') }] : []),
+        { id: 'AC203', text: 'Form fields have visible labels', check: det('count', { selector: 'input:not([type=hidden]):not([type=submit]):not([aria-label]):not([id])', min: 0, max: 0 }) },
+        { id: 'AC204', text: 'Links and buttons say what they do', check: sem('Do the link and button texts describe what happens when they are used, rather than generic words like "click here"?') }
+      ]
+    }
   },
   a11y: {
     base: 300,
@@ -103,6 +113,20 @@ export const PACKS = {
   }
 }
 
+/** Page types a step (or the whole scenario) declares with `page`; the usability pack asks per type. */
+export const PAGE_TYPES = ['landing', 'work', 'list', 'settings', 'form', 'doc']
+
+/**
+ * The page type of a node: its own `page`, then the scenario's `page`, else inferred. A step with the seo pack or a
+ * scenario allowed on production is a public page (landing); anything else is an app screen (work).
+ */
+export function pageTypeOf (node, scenario = {}) {
+  if (node?.page) return node.page
+  if (scenario?.page) return scenario.page
+  if ((node?.packs || []).includes('seo') || (scenario?.environments || []).includes('production')) return 'landing'
+  return 'work'
+}
+
 /**
  * Adds the criteria of each pack listed on a node (`node.packs`) that the node does not already define.
  * Mutates and returns the scenario; safe to call twice.
@@ -117,7 +141,7 @@ export function expandPacks (scenario) {
     for (const name of node.packs) {
       const pack = PACKS[name]
       if (!pack) throw new Error(`node "${node.id}": unknown pack "${name}" (known: ${Object.keys(PACKS).join(', ')})`)
-      for (const c of pack.criteria({ locales })) {
+      for (const c of pack.criteria({ locales, page: pageTypeOf(node, scenario) })) {
         if (have.has(c.id)) continue
         node.criteria.push({ ...c, pack: name })
         have.add(c.id)

package/src/lib/run.mjs

@@ -64,7 +64,7 @@ export async function resolveRun ({ root, output, run }) {
     dir = join(base, id)
   }
   const meta = await readJson(join(dir, 'meta.json'), null)
-  if (!meta) throw new UserError(`Run directory ${dir} has no meta.json`)
+  if (!meta) throw new UserError(`${dir} is not a complete run (meta.json is missing). Start a new one with kaloko start, or delete the folder if it is left over.`)
   return { dir, meta, paths: runPaths(dir) }
 }
 

package/src/lib/scenario.mjs

@@ -5,8 +5,31 @@ import { UserError } from './util.mjs'
 import { expandPacks } from './packs.mjs'
 import { jsGuard } from './assertions.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
+const MAX_VALUES = 1_000_000
+const MAX_DEPTH = 64
+
+/** The data of a scenario's YAML text; a UserError when it is no YAML or expands beyond MAX_VALUES or MAX_DEPTH. */
+export function parseScenario (text, file = 'scenario') {
+  let data
+  try { data = yaml.load(text) } catch (e) { throw new UserError(`Scenario ${file} is not valid YAML: ${String(e?.message || e).split('\n')[0]}`) }
+  let n = 0
+  const stack = [[data, 0]]
+  while (stack.length) {
+    const [v, depth] = stack.pop()
+    if (!v || typeof v !== 'object') continue
+    if (depth >= MAX_DEPTH) throw new UserError(`Scenario ${file} is nested deeper than ${MAX_DEPTH} levels.`)
+    const kids = Object.values(v)
+    // counted before they are pushed, so a shared alias cannot grow the stack past the ceiling either
+    if ((n += kids.length) > MAX_VALUES) throw new UserError(`Scenario ${file} expands to more than ${MAX_VALUES} values (YAML aliases?).`)
+    for (const k of kids) stack.push([k, depth + 1])
+  }
+  return data
+}
+
 export async function loadScenario (file) {
-  const data = yaml.load(await readFile(file, 'utf8'))
+  const data = parseScenario(await readFile(file, 'utf8'), file)
   const problems = validateScenario(data)
   if (!problems.length) expandPacks(data)
   if (problems.length) throw new UserError(`Scenario ${file} is invalid:\n  - ${problems.join('\n  - ')}`)
@@ -54,6 +77,45 @@ export function validateScenario (data) {
   return problems
 }
 
+const TEXT_ASSERTS = new Set(['text_matches', 'text_absent', 'title_matches', 'meta_matches'])
+const ACCENTED = /[áčďéěíňóřšťúůýžäöüßąćęłńśźżàâçèêëîïôûùÿœñ]/i
+const EN_WORDS = new Set(['the', 'and', 'of', 'to', 'in', 'for', 'with', 'your', 'you', 'is', 'are', 'on', 'by', 'or', 'not', 'no', 'an', 'this', 'what', 'how'])
+const CS_WORDS = new Set(['a', 'i', 'v', 've', 'na', 'do', 'se', 'je', 'jsou', 'pro', 's', 'z', 'k', 'od', 'po', 'jak', 'co', 'nebo', 'ani', 'už', 'vaše', 'váš'])
+
+/** Language of one alternative of a text pattern: 'other' (diacritics or a Czech word), 'en' (an English word) or null. */
+function branchLanguage (branch) {
+  const text = branch.replace(/\\./g, ' ').replace(/\[[^\]]*\]/g, ' ')
+  if (ACCENTED.test(text)) return 'other'
+  const words = (text.match(/\p{L}+/gu) || []).map((w) => w.toLowerCase())
+  if (words.some((w) => CS_WORDS.has(w) && w.length > 1)) return 'other'
+  if (words.some((w) => EN_WORDS.has(w))) return 'en'
+  return null
+}
+
+/**
+ * Warnings that do not make a scenario invalid. A text criterion in a scenario with several locales whose pattern
+ * reads in one language only fails (or passes by accident) in the others. The heuristic is deliberately simple:
+ * the pattern is split at `|` and each alternative gets a language: a letter with a diacritic or a common Czech
+ * word means not English, a common English word ("the", "and", "your") means English, anything else (a brand,
+ * one plain word, "SOC 2") is unknown. It warns only when every alternative has a language and they all agree, so
+ * "Plans and payment" or "Vaše data" warn and "Your data|Vaše data", "Slack" or "Design drafts" do not.
+ * Pack criteria are left out.
+ */
+export function scenarioWarnings (data) {
+  const out = []
+  if (!data || (data.locales || []).length < 2 || !Array.isArray(data.nodes)) return out
+  for (const node of data.nodes) {
+    for (const c of node.criteria || []) {
+      const k = c.check || {}
+      if (c.pack || k.type !== 'deterministic' || !TEXT_ASSERTS.has(k.assert) || typeof k.pattern !== 'string') continue
+      const langs = k.pattern.split('|').map(branchLanguage)
+      if (langs.some((l) => !l) || new Set(langs).size !== 1) continue
+      out.push(`node "${node.id}": ${c.id} pattern /${k.pattern}/ reads in one language only, but the scenario walks ${data.locales.join(', ')}; add the other language as an alternative (English|Czech) or move the check to a per-locale step`)
+    }
+  }
+  return out
+}
+
 /**
  * Layered layout: column = longest path from a root, lane = explicit `lane`
  * or inherited from the parent (+1 for each extra `alt` branch).

package/src/lib/service.mjs

@@ -19,19 +19,49 @@ export function ciName (vars = process.env) {
   return vars.CI && vars.CI !== 'false' ? 'ci' : null
 }
 
+/** What to do after the service answered `status`; '' when its own message says enough. */
+export function nextStepFor (status, { tokenEnv = 'KALOKO_TOKEN', url = 'https://kaloko.app' } = {}) {
+  if (status === 401) return `The token in ${tokenEnv} is invalid, expired or revoked. Run kaloko login for a new one (or put a fresh token from Settings → API tokens into .env).`
+  if (status === 403) return 'Your role or the token\'s scopes do not allow this; ask an admin of the organization, or use a token that may do it.'
+  if (status === 413) return 'The file is larger than the service takes; leave it out of the run or make it smaller.'
+  if (status === 429) return 'The service is limiting requests from this token. Wait a minute and run the command again.'
+  if (status >= 500) return `The service had a problem on its side. Try again in a few minutes; ${url}/status says whether it is a known outage.`
+  return ''
+}
+
+/** A UserError for an HTTP answer: what failed, the service's message, what to do next; `status` kept for callers. */
+export function httpError (what, status, message, opts) {
+  const err = new UserError([`${what} → HTTP ${status}: ${message}`, nextStepFor(status, opts)].filter(Boolean).join(' '))
+  err.status = status
+  err.serviceMessage = message
+  return err
+}
+
+/** A UserError for a request that got no answer at all (offline, DNS, refused, TLS). */
+export function unreachable (url, e) {
+  const code = e?.cause?.code || e?.code || e?.message || 'no answer'
+  const err = new UserError(`Cannot reach ${url} (${code}). Check your network or VPN and run the command again; KALOKO_URL points the CLI to another service.`)
+  err.offline = true
+  return err
+}
+
 export function service (config) {
-  const base = serviceUrl(config) + '/api/v1'
+  const root = serviceUrl(config)
+  const base = root + '/api/v1'
   const tokenEnv = config.share?.token_env || 'KALOKO_TOKEN'
   const token = process.env[tokenEnv]
-  if (!token) throw new UserError(`Set ${tokenEnv} (create a token in Kaloko → Settings).`)
+  if (!token) throw new UserError(`${tokenEnv} is not set, so the CLI cannot reach your organization on ${root}. Run kaloko login, or create a token in Settings → API tokens and put ${tokenEnv}=… into .env.`)
+  const opts = { tokenEnv, url: root }
   // an agent names itself (KALOKO_AGENT, e.g. "claude-code"); the service shows it in presence, history and audit (#42)
   const ci = ciName()
   const headers = { Authorization: `Bearer ${token}`, ...(process.env.KALOKO_AGENT ? { 'X-QAwalk-Agent': process.env.KALOKO_AGENT.slice(0, 60) } : {}), ...(ci ? { 'X-Kaloko-CI': ci } : {}) }
   const check = async (res, what) => {
     if (res.ok) return res.json()
     const body = await res.json().catch(() => ({}))
-    throw new UserError(`${what} → HTTP ${res.status}: ${body.error || res.statusText}`)
+    throw httpError(what, res.status, body.error || res.statusText, opts)
   }
+  // fetch rejects without an answer (offline, refused, DNS): say so instead of a stack trace
+  const call = (send) => send().catch((e) => { if (e instanceof UserError) throw e; throw unreachable(root, e) })
   // the service limits requests per token (HTTP 429, nothing was processed): wait as told and try again
   // read-your-writes across requests: the service answers with a database bookmark the next request sends back
   let bookmark = null
@@ -46,18 +76,18 @@ export function service (config) {
   }
   return {
     async request (method, path, body) {
-      const res = await limited(() => fetch(base + path, { method, headers: { ...headers, ...(body ? { 'Content-Type': 'application/json' } : {}) }, body: body ? JSON.stringify(body) : undefined }))
+      const res = await call(() => limited(() => fetch(base + path, { method, headers: { ...headers, ...(body ? { 'Content-Type': 'application/json' } : {}) }, body: body ? JSON.stringify(body) : undefined })))
       return check(res, `${method} ${path}`)
     },
     /** A request whose answer is not JSON (an export): the response, or an error with the service's message. */
     async raw (method, path, body) {
-      const res = await limited(() => fetch(base + path, { method, headers: { ...headers, ...(body ? { 'Content-Type': 'application/json' } : {}) }, body: body ? JSON.stringify(body) : undefined }))
-      if (!res.ok) { const b = await res.json().catch(() => ({})); throw new UserError(`${method} ${path} → HTTP ${res.status}: ${b.error || res.statusText}`) }
+      const res = await call(() => limited(() => fetch(base + path, { method, headers: { ...headers, ...(body ? { 'Content-Type': 'application/json' } : {}) }, body: body ? JSON.stringify(body) : undefined })))
+      if (!res.ok) { const b = await res.json().catch(() => ({})); throw httpError(`${method} ${path}`, res.status, b.error || res.statusText, opts) }
       return res
     },
     async fetch (path) {
-      const res = await fetch(base + path, { headers })
-      if (!res.ok) { const body = await res.json().catch(() => ({})); throw new UserError(`GET ${path} → HTTP ${res.status}: ${body.error || res.statusText}`) }
+      const res = await call(() => limited(() => fetch(base + path, { headers })))
+      if (!res.ok) { const body = await res.json().catch(() => ({})); throw httpError(`GET ${path}`, res.status, body.error || res.statusText, opts) }
       return res
     },
     async upload (path, data, name, extra = {}) {
@@ -65,7 +95,7 @@ export function service (config) {
         // a dropped connection (flaky Wi-Fi, CI runner hiccup) is tried again like a 5xx; the next share resumes otherwise
         let res
         try { res = await limited(() => fetch(base + path, { method: 'PUT', headers: { ...headers, ...extra }, body: data })) } catch (e) {
-          if (attempt >= 3) throw new UserError(`upload ${name}: ${e.cause?.code || e.message}. Run kaloko share again: files already stored are not sent twice.`)
+          if (attempt >= 3) throw new UserError(`The upload of ${name} broke off (${e.cause?.code || e.message}). Check your network and run kaloko share again: files already stored are not sent twice.`)
           await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)))
           continue
         }

package/src/lib/stability.mjs

@@ -129,7 +129,7 @@ export async function detectUnstable ({ root, config, run, scenario, last = 4, r
   const others = runs ? (await Promise.all(runs.map(async (id) => {
     const dir = id.includes('/') ? resolve(id) : join(resolve(root, config.output), id)
     const meta = await readJson(join(dir, 'meta.json'), null)
-    if (!meta) throw new UserError(`Run ${id} not found in ${config.output}.`)
+    if (!meta) throw new UserError(`Run ${id} is not in ${config.output}. kaloko runs lists the runs here.`)
     return { dir, meta }
   }))) : (await siblingRuns({ root, config, run, sameCommit })).slice(0, Math.max(0, last - 1))
   const all = [{ dir: run.dir, meta: run.meta }, ...others]
@@ -292,7 +292,7 @@ export async function pullDrawn ({ root, config, run, args, say, client }) {
   const scenarioId = typeof args.scenario === 'string' ? args.scenario : run.meta.scenario.id
   const data = await client.request('GET', `/orgs/${config.org}/scenarios/${encodeURIComponent(scenarioId)}/ignore-regions`)
   const regions = data.regions || []
-  if (!regions.length) { say(`No drawn regions wait for ${scenarioId}. Draw them on a screenshot on kaloko.app (step detail → Page → Draw a region).`); return { applied: [], skipped: [], regions: [] } }
+  if (!regions.length) { say(`No drawn regions wait for ${scenarioId}. Draw them on a screenshot on kaloko.app (step detail → Mark a changing region).`); return { applied: [], skipped: [], regions: [] } }
   const byNode = new Map()
   for (const r of regions) (byNode.get(r.node_id) || byNode.set(r.node_id, []).get(r.node_id)).push(r.scenario_entry)
   const file = resolve(root, run.meta.scenario_file)