kaloko 0.8.0 → 0.10.0

package/src/cli.mjs

@@ -20,7 +20,7 @@ import { evaluateRun, semanticPrefetch } from './lib/evaluate.mjs'
 import { buildManifest, writePreview, attentionLines } from './lib/build.mjs'
 import { stabilityCmd, pullDrawn } from './lib/stability.mjs'
 import { signoffCmd } from './lib/signoff.mjs'
-import { localized, readJson, UserError, globToRegExp, failureStreak, expiryNote } from './lib/util.mjs'
+import { localized, readJson, UserError, globToRegExp, failureStreak, expiryNote, SUPPORT_LINE, SUPPORT_EMAIL, NO_ORG } from './lib/util.mjs'
 import { packageRoot } from './lib/schema.mjs'
 import { compareRuns, formatComparison } from './lib/compare.mjs'
 import { doctor, formatDoctor } from './lib/doctor.mjs'
@@ -29,7 +29,7 @@ import { calibrate, formatCalibration, casesFromGolden, casesFromRun } from './l
 import { pageFacts, draftScenario, scenarioYaml } from './lib/draft.mjs'
 import { detectProject, initScenario, formatDetection } from './lib/init-detect.mjs'
 import { recheckCaptures } from './lib/recheck.mjs'
-import { resolveItems, fieldsOf, DEFAULT_LIMIT } from './lib/stack.mjs'
+import { resolveItems, fieldsOf, DEFAULT_LIMIT, timeLeft } from './lib/stack.mjs'
 import { DEFAULTS as JEV_DEFAULTS } from './lib/jev.mjs'
 import { expandPacks } from './lib/packs.mjs'
 import { upsertPrComment } from './lib/pr.mjs'
@@ -50,6 +50,7 @@ import { walkDesign, syncDesign, publishVersion, previewNotes, historyCmd, refer
 import { screensCmd } from './lib/screens-cli.mjs'
 import { designDir, readBase, headKey } from './lib/design.mjs'
 import { lintDesign, formatLint } from './lib/design-lint.mjs'
+import { cleanAssetOrigins } from './lib/design-origins.mjs'
 import { exportDesign } from './lib/design-export.mjs'
 import { driverFor, isApp, pngSize, ocr as ocrImage } from './lib/apps/drivers.mjs'
 import { captureApp } from './lib/apps/capture.mjs'
@@ -57,7 +58,7 @@ import { readTree, flatten } from './lib/apps/tree.mjs'
 import { recordSettings, recordingSession, parseRecord, recordingFiles, traceFiles, stripRecordings, withoutRecordings } from './lib/recording.mjs'
 import { nativeSession } from './lib/apps/recording-native.mjs'
 import { videoCmd } from './lib/video-cli.mjs'
-import { passesOf, enginesOf, contextOptionsOf, launchEngine, pickKeys, variantFields, variantOf, dimensionValues, BROWSERS } from './lib/dimensions.mjs'
+import { passesOf, enginesOf, contextOptionsOf, launchEngine, pickKeys, variantFields, variantOf, dimensionValues, stateKeys, nodeStates, BROWSERS } from './lib/dimensions.mjs'
 import { startScope, scopeKeys, dimensionLine, baseViewports, engineKeys, appDeviceGroups } from './lib/walk-dimensions.mjs'
 import { deviceConfig, prepareAndroid, readyAndroid, finishAndroid, prepareSimulator, applyAppAppearance } from './lib/apps/devices.mjs'
 import { attachAndroidWebView } from './lib/apps/webview.mjs'
@@ -94,7 +95,9 @@ Project
                                     the organization and what the token may do; the token (at most 30 days) goes to
                                     ~/.config/kaloko/.env, or is printed with --print
   doctor [--json] [--fix]           Check Node, Chrome, config, environments, browser ports, token, evaluator key
-                                    and app tools; --fix asks macOS for the desktop capture permissions
+                                    and app tools; --fix installs missing Playwright browsers, creates the run and
+                                    scenario folders, writes org: from the token and asks macOS for the desktop
+                                    capture permissions
   validate <scenario.yml>... [--coverage [--source ACCEPTANCE.md]]
                                     Validate scenarios (schema + references); --coverage compares criteria with the plan
                                     With a token it also warns about scenarios the service still lists whose file is gone (--offline skips it)
@@ -111,6 +114,9 @@ Run
                                     More dimensions: every step is captured in each combination (keys like
                                     mobile.webkit.dark); default from the scenario, then walk: in the config
        [--devices pixel-8-api-34,iphone-15-ios-18]   App scenarios: the emulators, simulators or devices to walk on
+       [--states empty,error]       Only these step states (states: on a step; keys like mobile.state-empty)
+       [--token-modes brand-a,brand-b | --token-modes none]
+                                    Design environments: the token modes to render (default every mode of the set)
   browser start|stop|status [--env e] [--headed]   One shared browser per environment (port = browser.port + index)
                                     Shared Chromium with CDP (agents, scripts and people drive it)
   browser install [--with-deps] [--browsers chromium,webkit,firefox]
@@ -119,8 +125,8 @@ Run
   devices [--json]                  Device presets for viewports: (phones, foldables, tablets, laptop, desktop, TV)
   open --step <id> [--locale l]     Navigate the current page to the step URL
   session reset                     New visitor: clear cookies and storage in the shared browser
-  capture --step <id> [--locale l] [--url <url>] [--page <substring>] [--viewports a,b]
-                                    Capture the current page for a step in all viewports
+  capture --step <id> [--locale l] [--url <url>] [--page <substring>] [--viewports a,b] [--state <name>]
+                                    Capture the current page for a step in all viewports (--state: as that step state)
   capture --step <id> --crop <css> [--title <text>]
                                     Attach an element screenshot to a step
   capture --step <id> --image <shot.png> [--tree <dump.xml|json> | --ocr] [--platform android|ios|desktop]
@@ -305,9 +311,11 @@ Design (environments with kind: design; live HTML steps in a folder)
   sync [--pull|--push] [--branch b] [--mine a,b|--theirs a,b] [--no-lint]
                                     Exchange revisions with the shared draft; only changed steps and missing files travel
                                     Lints the folder first: errors (things that break on the live step) stop the push
-  design lint [--env e | --dir design/] [--scenario file] [--all] [--strict] [--json]
+  design lint [--env e | --dir design/] [--scenario file] [--all] [--strict] [--offline] [--json]
                                     Check the folder against the portable HTML rules (relative URLs, no CDNs, no storage,
-                                    deterministic content, viewport, lang, links that also work from disk); --strict fails on warnings
+                                    deterministic content, viewport, lang, links that also work from disk); --strict fails on warnings.
+                                    Fonts, styles and images from origins of the environment are compared with the
+                                    organization's allowed origins (--offline skips that)
   share [--name <text>] [--branch b] [--notes file|-] [--notes-preview]
                                     Publish the draft as a version of the flow (a run): "v4 · 3 changed, 17 unchanged",
                                     with "what changed" notes per step (screens per viewport, text, tokens); --notes-preview
@@ -319,7 +327,7 @@ Design (environments with kind: design; live HTML steps in a folder)
                                     a folder exported from Figma works without a token. One way: no prototype links
   history [--scenario id] [--step id] [--locale l] [--json]
                                     Versions of the flow; revisions of a step with who (person or agent) and when
-  spec [step] [--ref design|draft|vN|<run id>] [--locale l] [--viewport v] [--local] [--json]
+  spec [step] [--ref design|draft|vN|<run id>] [--locale l] [--viewport v] [--state s] [--local] [--json]
                                     What to build for a step as approved: elements with role, name and selector, styles
                                     mapped to DTCG tokens (or the nearest one), :hover/:focus/:active/:disabled, contrast
   drift [step] [--ref design|vN] [--remote <run id|latest>] [--json]
@@ -449,12 +457,27 @@ async function runContext (args) {
 }
 
 function stepOf (scenario, id) {
-  if (!id) throw new UserError('--step <id> is required.')
+  if (!id) throw new UserError(`Which step? Pass --step <id>; this scenario has: ${scenario.nodes.filter((n) => n.kind !== 'decision').map((n) => n.id).join(', ')}.`)
   const node = scenario.nodes.find((n) => n.id === id)
   if (!node) throw new UserError(`Unknown step "${id}". Steps: ${scenario.nodes.filter((n) => n.kind !== 'decision').map((n) => n.id).join(', ')}`)
   return node
 }
 
+/**
+ * Font and asset origins for `kaloko design lint` (#46): `wanted` from `origins` of the design environment, and with
+ * `online` the organization's list from the service (GET /me design_origins; null when not signed in or unreachable).
+ */
+async function lintOrigins (config, env, { online = false } = {}) {
+  let wanted = []
+  try { wanted = cleanAssetOrigins(env?.origins || []) } catch (e) { throw new UserError(`Environment ${env.name}, origins: ${e.message}`) }
+  if (!online || !wanted.length) return { wanted, allowed: null }
+  let timer
+  try {
+    const me = await Promise.race([service(config).request('GET', '/me'), new Promise((resolve, reject) => { timer = setTimeout(() => reject(new Error('timeout')), 8000) })])
+    return Array.isArray(me?.design_origins) ? { wanted, allowed: me.design_origins } : { wanted, allowed: null, unchecked: true }
+  } catch { return { wanted, allowed: null, unchecked: true } } finally { clearTimeout(timer) }
+}
+
 /** Scenario of --scenario (id or file) or of the current run. */
 /**
  * kaloko design import figma <file-url|key|folder>: Figma frames (or a folder exported from Figma) become the steps of
@@ -486,7 +509,7 @@ async function designImport (args) {
   if (args.json) say(JSON.stringify(r, null, 2))
   else say(formatImport(r, { dir: relative(process.cwd(), dir) || '.' }))
   if (args['dry-run']) return r
-  const lint = await lintDesign({ dir, scenario })
+  const lint = await lintDesign({ dir, scenario, origins: await lintOrigins(config, env) })
   if (lint.errors) say(`\n${formatLint(lint, { max: 10 })}`)
   if (!args.publish) {
     say(`\nNext: kaloko start --scenario ${relative(process.cwd(), scenarioFile)} --env ${env.name} && kaloko walk && kaloko share (or rerun with --publish).\nAccept the version on the canvas and set it as the design reference (kaloko reference --design --version <n>): implementation runs with packs: [design] are then checked against these frames.`)
@@ -519,6 +542,24 @@ function manualKeys (run, pick) {
   return scopeKeys(scope, keys.length ? keys : engineKeys(scope, 'chromium'), null)
 }
 
+/** Modes of a design environment's token set (tokens.resolver.json or tokens.json); [] without one. */
+async function designTokenModesOf (config, root, env) {
+  try {
+    const { loadTokens } = await import('./lib/drift.mjs')
+    const { modesOf } = await import('./lib/tokens.mjs')
+    const set = await loadTokens({ client: null, config, root, designDir: designDir(env, root) })
+    return set ? modesOf(set) : []
+  } catch { return [] }
+}
+
+/** --state <name> (#46): the keys of that state of the step instead of the default ones. */
+function inState (run, node, keys, state) {
+  if (!state || state === true || state === 'default') return keys
+  const have = nodeStates(run.meta.scope, node)
+  if (!have.includes(state)) throw new UserError(`Step ${node.id} has no state "${state}" in this run (${have.length > 1 ? `its states: ${have.join(', ')}` : 'add states: to the step and start a new run'}).`)
+  return Object.fromEntries(stateKeys(run.meta.scope, Object.keys(keys), state).map((k) => [k, run.meta.scope.viewports[k]]))
+}
+
 /** { key: [w, h] } a capture on a Chromium page takes: every Chromium key of the run, or those of `pick`. */
 function scopeViewports (run, pick) {
   return scopeKeys(run.meta.scope, engineKeys(run.meta.scope, 'chromium'), pick)
@@ -655,6 +696,7 @@ async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir,
   page.on('response', onResponse)
   const streak = failureStreak(5)
   const failed = []; let ok = 0
+  const started = Date.now(); let told = started
   try {
     for (const [i, item] of chosen.entries()) {
       if (streak.stopped('stack')) { failed.push(`${item.id}: not walked after repeated failures`); continue }
@@ -671,7 +713,8 @@ async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir,
         failed.push(`${item.id} (${item.path}): ${error.message.split('\n')[0]}`)
         if (streak.record('stack', error.message)) say(`  stopping ${node.id} (${locale}${tag}): the last 5 pages failed with the same error`)
       }
-      if ((i + 1) % 25 === 0 && i + 1 < chosen.length) say(`  ${node.id} ${locale}: ${i + 1}/${chosen.length}`)
+      // long stacks: progress every 25 pages (or 30 s) with the time left, estimated from the pages so far
+      if (i + 1 < chosen.length && ((i + 1) % 25 === 0 || Date.now() - told > 30000)) { told = Date.now(); const left = timeLeft(i + 1, chosen.length, told - started); say(`  ${node.id} ${locale}: ${i + 1}/${chosen.length}${left ? ` · ${left}` : ''}`) }
     }
   } finally { page.off('response', onResponse) }
   say(`${failed.length ? '✗' : '✓'} ${node.id} ${locale}${tag}: ${ok}/${chosen.length} page(s) captured`)
@@ -768,15 +811,17 @@ async function walkApp ({ config, root, run, scenario, env, args }) {
             if (!scripted && !(link && ['playwright', 'script'].includes(node.execution?.strategy))) { pending.push(`${node.id} (${locale}): ${node.execution?.strategy || 'agent'} — ${(node.execution?.instructions || '').split('\n')[0]}`); continue }
             const streakKey = `${group.device || ''}|${locale}`
             if (streak.stopped(streakKey)) { skipped.push(`${node.id} (${locale}${tag})`); continue }
-            const records = []
+            let records = []
+            // step states (#46): the script (or the deep link) runs once per state; `state` tells the script which
+            let state = 'default'
             try {
               let captured = false
               await rec?.beforeStep(node)
               const capture = async (o = {}) => {
                 captured = true
-                await rec?.beforeCapture(node)
+                if (state === 'default') await rec?.beforeCapture(node)
                 // a named viewport: within this device, or any of the run when it has no devices (as before)
-                const keys = o.viewport ? pickKeys(scope, group.device ? group.keys : Object.keys(scope.viewports), [o.viewport]) : group.keys
+                const keys = stateKeys(scope, o.viewport ? pickKeys(scope, group.device ? group.keys : Object.keys(scope.viewports), [o.viewport]) : group.keys, state)
                 if (!keys.length) throw new UserError(`Unknown viewport "${o.viewport}" for ${group.device || platform}.`)
                 const out = []
                 for (const key of keys) {
@@ -799,14 +844,25 @@ async function walkApp ({ config, root, run, scenario, env, args }) {
                 records.push(...out)
                 return out.length === 1 ? out[0] : out
               }
-              if (scripted) {
-                const mod = await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href)
-                await mod.default({ app: driver, page: driver.page || null, webview: driver.webview || null, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, device: group.device, env, run: run.meta, capture, link: (id = node.id) => linkFor(env, stepOf(scenario, id), locale), url: (id = node.id) => linkFor(env, stepOf(scenario, id), locale) })
-              } else await driver.link(link)
-              if (!captured) await capture()
+              const mod = scripted ? await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href) : null
+              const once = async () => {
+                captured = false
+                if (mod) await mod.default({ app: driver, page: driver.page || null, webview: driver.webview || null, locale, state, node: { id: node.id, title: localized(node.title, locale), kind: node.kind, ...(node.states ? { states: nodeStates(scope, node) } : {}) }, device: group.device, env, run: run.meta, capture, link: (id = node.id) => linkFor(env, stepOf(scenario, id), locale), url: (id = node.id) => linkFor(env, stepOf(scenario, id), locale) })
+                else await driver.link(link)
+                if (!captured) await capture()
+              }
+              await once()
               await rec?.afterStep(node, driver.web ? { records } : { record: records[0] })
               say(`✓ ${node.id} ${locale}${tag}`)
               streak.ok(streakKey)
+              for (const s of nodeStates(scope, node).slice(1)) {
+                state = s; records = []
+                try { await once(); say(`✓ ${node.id} ${locale}${tag} · ${s}`) } catch (error) {
+                  failed.push(`${node.id} (${locale}${tag} · ${s}): ${error.message.split('\n')[0]}`)
+                  say(`✗ ${node.id} ${locale}${tag} · ${s}: ${error.message.split('\n')[0]}`)
+                }
+              }
+              state = 'default'
             } catch (error) {
               await rec?.afterStep(node, driver.web ? { error, records } : { error, record: records[0] }).catch(() => {})
               failed.push(`${node.id} (${locale}${tag}): ${error.message.split('\n')[0]}`)
@@ -1022,7 +1078,9 @@ const commands = {
     if (scenario.environments && !scenario.environments.includes(env.name)) throw new UserError(`Scenario ${scenario.id} is not allowed on ${env.name} (allowed: ${scenario.environments.join(', ')}).`)
     if (env.readonly && !scenario.readonly) throw new UserError(`Environment ${env.name} is readonly; the scenario must declare readonly: true.`)
     const locales = list(args.locales) || scenario.locales || ['default']
-    const scope = { ...startScope({ args, scenario, config, env }), ...(args.note ? { note: args.note } : {}) }
+    // design environments render every mode of their token set (#46): the modes come from the folder's set
+    const tokenModes = env.kind === 'design' ? await designTokenModesOf(config, root, env) : []
+    const scope = { ...startScope({ args, scenario, config, env, tokenModes }), ...(args.note ? { note: args.note } : {}) }
     scope.locales = locales
     const vpNames = baseViewports(scope)
     const git = await gitMeta(root)
@@ -1101,7 +1159,8 @@ const commands = {
     }
     if (isApp(scenario.platform)) {
       // the app's current screen, through the environment's driver (no navigation); --viewport may name a device key
-      const key = typeof args.viewport === 'string' ? args.viewport : Object.keys(run.meta.scope.viewports || {})[0]
+      const key0 = typeof args.viewport === 'string' ? args.viewport : Object.keys(run.meta.scope.viewports || {})[0]
+      const key = Object.keys(inState(run, node, { [key0]: run.meta.scope.viewports[key0] }, args.state))[0] || key0
       const device = run.meta.scope.devices?.[variantOf(run.meta.scope, key).viewport]?.app ? variantOf(run.meta.scope, key).viewport : null
       const cfg = deviceConfig(scenario.platform, env.app?.[scenario.platform] || {}, device)
       const driver = driverFor(scenario.platform, { ...env, app: { ...(env.app || {}), [scenario.platform]: cfg } }, { root, scenarioDir: resolve(root, run.meta.scenario_file, '..'), locale })
@@ -1135,7 +1194,7 @@ const commands = {
         return
       }
       const since = (await readCaptures(run.dir)).filter((c) => c.node === node.id).map((c) => c.at).pop()
-      const results = await captureStep({ page, node, locale, options: captureOptions(scenario, node), viewports: manualKeys(run, list(args.viewports)), run, consoleFile: conn ? consoleLog(root, config.output, env.name) : null, maxChars: config.evaluators?.jev?.max_state_chars, since, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, stability: Number(args.stability) || 0 })
+      const results = await captureStep({ page, node, locale, options: captureOptions(scenario, node), viewports: inState(run, node, manualKeys(run, list(args.viewports)), args.state), run, consoleFile: conn ? consoleLog(root, config.output, env.name) : null, maxChars: config.evaluators?.jev?.max_state_chars, since, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, stability: Number(args.stability) || 0 })
       for (const r of results) {
         const failed = Object.entries(r.checks).filter(([, v]) => v.ok === false).map(([k]) => k)
         say(`✓ ${node.id} ${locale} ${r.viewport}  ${r.size.width}×${r.size.height}px  ${failed.length ? `failing checks: ${failed.join(', ')}` : 'checks ok'}${r.blocked_requests.length ? `  blocked: ${r.blocked_requests.length}` : ''}`)
@@ -1193,8 +1252,8 @@ const commands = {
       }
     }
     if (env.kind === 'design') {
-      await walkDesign({ config, root, run, scenario, env, pick: list(args.steps), locales: list(args.locales) || run.meta.scope.locales, viewports: scopeViewports(run, list(args.viewports)), say, noCache: !!args['no-cache'] })
-      const lint = await lintDesign({ dir: designDir(env, root), scenario })
+      await walkDesign({ config, root, run, scenario, env, pick: list(args.steps), locales: list(args.locales) || run.meta.scope.locales, viewports: scopeKeys(run.meta.scope, engineKeys(run.meta.scope, 'chromium', '*'), list(args.viewports)), say, noCache: !!args['no-cache'] })
+      const lint = await lintDesign({ dir: designDir(env, root), scenario, origins: await lintOrigins(config, env) })
       if (lint.errors || lint.warnings) say(`\nPortable HTML: ${lint.errors} error(s), ${lint.warnings} warning(s); kaloko design lint lists them${lint.errors ? ' (errors stop kaloko sync: they break on the live step)' : ''}.`)
       return
     }
@@ -1337,22 +1396,32 @@ const commands = {
               const scriptFile = resolve(scenarioDir, node.execution.script)
               // one invocation of the step script; the automatic capture runs unless the script captured the step itself:
               // a crop is an attachment (#49), and a capture from an earlier walk must not stand in for this one (#50)
-              const rec = await recorderFor(sPage)
-              const runStep = async (mod) => {
+              const rec0 = await recorderFor(sPage)
+              // step states (#46): the script runs once per state with `state`; each run captures that state's keys
+              // (the recording follows the default state)
+              const runStep = async (mod, state = 'default') => {
                 let captured = false
+                const rec = state === 'default' ? rec0 : null
                 rec?.beforeStep(node)
                 const records = []
-                const capture = (opts = {}) => { captured = true; rec?.beforeCapture(node); return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeKeys(run.meta.scope, pass.keys, opts.viewports || null), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {}, stability: Number(args.stability) || 0 }).then((r) => { prefetch?.add(r, run.dir); records.push(...r); return r }) }
+                const capture = (opts = {}) => { captured = true; rec?.beforeCapture(node); return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeKeys(run.meta.scope, stateKeys(run.meta.scope, Object.keys(scopeKeys(run.meta.scope, pass.keys, opts.viewports || null)), state)), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile, maxChars: config.evaluators?.jev?.max_state_chars, extra: node.session ? { session: node.session } : {}, stability: Number(args.stability) || 0 }).then((r) => { prefetch?.add(r, run.dir); records.push(...r); return r }) }
                 try {
-                  await mod.default({ page: sPage, context: sCtx, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, session: sessionInfo(node.session), url: (id = node.id) => urlFor(env, stepOf(scenario, id), locale), env, run: run.meta, capture, crop: (selector, title, o = {}) => captureCrop({ page: sPage, node, locale, selector, title, run, padding: Number(o.padding) || 0 }), acceptDialogs: () => acceptDialogs(sPage) })
+                  await mod.default({ page: sPage, context: sCtx, locale, state, node: { id: node.id, title: localized(node.title, locale), kind: node.kind, ...(node.states ? { states: nodeStates(run.meta.scope, node) } : {}) }, session: sessionInfo(node.session), url: (id = node.id) => urlFor(env, stepOf(scenario, id), locale), env, run: run.meta, capture, crop: (selector, title, o = {}) => captureCrop({ page: sPage, node, locale, selector, title, run, padding: Number(o.padding) || 0 }), acceptDialogs: () => acceptDialogs(sPage) })
                   if (!captured) await capture()
                 } catch (error) { await rec?.afterStep(node, { error }); throw error }
                 await rec?.afterStep(node, { records })
               }
               try {
-                await runStep(await import(pathToFileURL(scriptFile).href))
+                const mod = await import(pathToFileURL(scriptFile).href)
+                await runStep(mod)
                 say(`✓ ${node.id} ${locale}${tag}`)
                 streak.ok(streakKey)
+                for (const state of nodeStates(run.meta.scope, node).slice(1)) {
+                  try { await runStep(mod, state); say(`✓ ${node.id} ${locale}${tag} · ${state}`) } catch (error) {
+                    failed.push(`${node.id} (${locale}${tag} · ${state}): ${error.message.split('\n')[0]}`)
+                    say(`✗ ${node.id} ${locale}${tag} · ${state}: ${error.message.split('\n')[0]}`)
+                  }
+                }
               } catch (error) {
                 // a selector the page no longer has: propose one from the page (#13); --heal applies it once the step passes
                 const healed = args['no-heal'] ? null : await healStep({ error, page: sPage, scriptFile, root, output: config.output, run, node, locale, apply: !!args.heal, rerun: runStep }).catch(() => null)
@@ -1792,7 +1861,7 @@ const commands = {
     const client = service(config)
     if (env.kind === 'design' && !args.pull && !args['no-lint']) {
       // what renders locally may still break on the live step (CSP, sandbox): say so before anything is pushed
-      const lint = await lintDesign({ dir: designDir(env, root), scenario })
+      const lint = await lintDesign({ dir: designDir(env, root), scenario, origins: await lintOrigins(config, env, { online: true }) })
       if (lint.errors || lint.warnings) say(formatLint(lint, { max: 15 }) + '\n')
       if (lint.errors) throw new UserError(`${lint.errors} error(s) above break the design on the live step; fix them, or sync with --no-lint to push anyway.`)
     }
@@ -1801,19 +1870,19 @@ const commands = {
 
   async design (args) {
     if (args._[0] === 'import') return designImport(args)
-    if (args._[0] !== 'lint') throw new UserError('Usage: kaloko design lint [--env <design env> | --dir design/] [--scenario file] [--all] [--strict] [--json]\n       kaloko design import figma <file-url|key|export folder> [--frames a,b] [--map frames.json] [--token-env FIGMA_TOKEN] [--publish]')
+    if (args._[0] !== 'lint') throw new UserError('Usage: kaloko design lint [--env <design env> | --dir design/] [--scenario file] [--all] [--strict] [--offline] [--json]\n       kaloko design import figma <file-url|key|export folder> [--frames a,b] [--map frames.json] [--token-env FIGMA_TOKEN] [--publish]')
     const { config, root } = await context(args)
     let run = null
     try { run = await resolveRun({ root, output: config.output, run: args.run }) } catch {}
     let dir = typeof args.dir === 'string' ? resolve(args.dir) : null
+    const runEnv = run ? environment(config, run.meta.environment.name) : null
+    const env = typeof args.env === 'string' ? environment(config, args.env) : runEnv?.kind === 'design' ? runEnv : Object.keys(config.environments || {}).map((n) => environment(config, n)).find((e) => e.kind === 'design')
     if (!dir) {
-      const runEnv = run ? environment(config, run.meta.environment.name) : null
-      const env = typeof args.env === 'string' ? environment(config, args.env) : runEnv?.kind === 'design' ? runEnv : Object.keys(config.environments).map((n) => environment(config, n)).find((e) => e.kind === 'design')
       if (!env) throw new UserError('No design environment: pass --dir <folder> or --env <design env>.')
       dir = designDir(env, root)
     }
     const scenario = typeof args.scenario === 'string' && /\.ya?ml$/.test(args.scenario) ? await loadScenario(resolve(args.scenario)) : run ? await loadScenario(resolve(root, run.meta.scenario_file)).catch(() => null) : null
-    const report = await lintDesign({ dir, scenario })
+    const report = await lintDesign({ dir, scenario, origins: env?.kind === 'design' ? await lintOrigins(config, env, { online: !args.offline }) : null })
     say(args.json ? JSON.stringify(report, null, 2) : formatLint(report, { all: !!args.all, max: args.all ? 500 : 60 }))
     if (report.errors || (args.strict && report.warnings)) process.exitCode = 1
   },
@@ -2106,9 +2175,9 @@ const commands = {
     }
     let runId = args.run
     if (!runId) { try { runId = (await resolveRun({ root, output: config.output })).meta.id } catch {} }
-    if (!runId) throw new UserError('--run <id> is required when there is no current run.')
+    if (!runId) throw new UserError('No current run here. Pass --run <id>, or walk the scenario first (kaloko start, then kaloko walk).')
     const run = await load(runId)
-    if (!run) throw new UserError(`Run ${runId} not found locally or on the service.`)
+    if (!run) throw new UserError(`Run ${runId} is neither in ${config.output} nor on the service. Check the id (kaloko runs lists the local ones; the run's address on Kaloko shows a shared one).`)
     let baseId = typeof args.baseline === 'string' ? args.baseline : null
     // --design: against the design reference of the scenario (#42)
     if (args.design && run.scenario?.id) { client ||= service(config); baseId = (await client.request('GET', `/orgs/${config.org}/scenarios/${encodeURIComponent(run.scenario.id)}/references`)).design; if (!baseId) throw new UserError('This scenario has no design reference yet (kaloko reference --design --version <n>).') }
@@ -2120,7 +2189,7 @@ const commands = {
     }
     if (!baseId) throw new UserError('No baseline or earlier run of this scenario to compare with; pass --baseline <id>.')
     const base = await load(baseId)
-    if (!base) throw new UserError(`Run ${baseId} not found locally or on the service.`)
+    if (!base) throw new UserError(`Baseline run ${baseId} is neither in ${config.output} nor on the service. Check the id, or pass another --baseline <id>.`)
     const d = compareRuns(run, base)
     if (args.json) { say(JSON.stringify(d, null, 2)); return }
     say(formatComparison(d))
@@ -2199,7 +2268,7 @@ const commands = {
     if (typeof args.scenario === 'string') return exportScenario({ args, config, root, client })
     if (typeof args.format === 'string') {
       // living docs and the changelog as files (docs/DOCS-CHANGELOG.md → Exports)
-      if (!config.org) throw new UserError('Set org: in the config first.')
+      if (!config.org) throw new UserError(NO_ORG)
       const { pickProduct } = await import('./lib/changelog.mjs')
       const { exportDocs } = await import('./lib/docs.mjs')
       const product = pickProduct(config, root, args.product)
@@ -2220,7 +2289,7 @@ const commands = {
     }
     let runId = args.run
     if (!runId) { try { runId = (await resolveRun({ root, output: config.output })).meta.id } catch {} }
-    if (!runId || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+$/.test(runId)) throw new UserError('--run <id> is required (a shared run id).')
+    if (!runId || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+$/.test(runId)) throw new UserError('Which run? Pass --run <id> with the id of a shared run (kaloko share prints it), or run this where kaloko start made a current run.')
     const out = typeof args.out === 'string' ? resolve(args.out) : resolve(root, config.output, `${runId}.zip`)
     const { createWriteStream } = await import('node:fs')
     const { Readable } = await import('node:stream')
@@ -2236,7 +2305,7 @@ const commands = {
     const client = service(config)
     let runId = args.run
     if (!runId) { try { runId = (await resolveRun({ root, output: config.output })).meta.id } catch {} }
-    if (!runId || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+$/.test(runId)) throw new UserError('--run <id> is required (a shared run id).')
+    if (!runId || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+$/.test(runId)) throw new UserError('Which run? Pass --run <id> with the id of a shared run (kaloko share prints it), or run this where kaloko start made a current run.')
     const r = await client.request('POST', `/orgs/${config.org}/runs/${runId}/public`, { public: !args.off })
     say(r.public ? `Public: ${r.url} (readable without sign-in; only one public run per scenario)` : `Private again: ${runId}`)
   },
@@ -2284,7 +2353,7 @@ const commands = {
     const product = pickProduct(config, root, args.product)
     const version = typeof args.version === 'string' ? args.version : 'latest'
     if (sub === 'publish') {
-      if (!config.org && !args['dry-run']) throw new UserError('Set org: in the config first.')
+      if (!config.org && !args['dry-run']) throw new UserError(NO_ORG)
       const r = await docs.publishDocs({ root, config, product, client: args['dry-run'] ? null : service(config), version, reviewed: !!args.reviewed, dryRun: !!args['dry-run'] })
       if (args.json) { say(JSON.stringify(r, null, 2)); return }
       if (r.dry_run) { say(`${product.slug}: ${r.pages} page(s) from ${r.dir} would go to Kaloko as ${r.version} (${r.languages.join(', ')}); dry run, nothing sent.${r.broken.length ? `\n  ! broken step references: ${r.broken.join('; ')}` : ''}`); return }
@@ -2312,12 +2381,12 @@ const commands = {
     const { config, root } = await context(args)
     const lib = await import('./lib/changelog.mjs')
     if (sub === 'list') {
-      if (!config.org) throw new UserError('Set org: in the config first.')
+      if (!config.org) throw new UserError(NO_ORG)
       const r = await lib.listProducts({ root, config, client: service(config) })
       say(args.json ? JSON.stringify(r, null, 2) : lib.formatList(r))
       return
     }
-    if (!config.org && !args['dry-run']) throw new UserError('Set org: in the config first.')
+    if (!config.org && !args['dry-run']) throw new UserError(NO_ORG)
     const r = await lib.syncProducts({ root, config, client: args['dry-run'] ? null : service(config), only: typeof args.product === 'string' ? args.product : null, dryRun: !!args['dry-run'] })
     say(args.json ? JSON.stringify(r, null, 2) : lib.formatSync(r))
     if (r.products.some((p) => p.ok === false)) process.exitCode = 1
@@ -2326,7 +2395,7 @@ const commands = {
   /** `kaloko release <version>`: the version's changelog entry and its reference runs on the service. */
   async release (args) {
     const { config, root } = await context(args)
-    if (!config.org) throw new UserError('Set org: in the config first.')
+    if (!config.org) throw new UserError(NO_ORG)
     const { pickProduct, releaseProduct } = await import('./lib/changelog.mjs')
     const product = pickProduct(config, root, args.product)
     const client = args['dry-run'] ? null : service(config)
@@ -2360,10 +2429,13 @@ export async function main (argv) {
   const args = parse(argv)
   const name = args._.shift() || 'help'
   const cmd = commands[name] || (args.help ? commands.help : null)
-  if (!cmd) { console.error(`Unknown command "${name}".\n`); say(HELP); process.exitCode = 2; return }
+  if (!cmd) { console.error(`There is no command "${name}". The commands are below; kaloko help <command> explains one.\n`); say(HELP); process.exitCode = 2; return }
   try {
     await cmd(args)
   } catch (error) {
-    if (error instanceof UserError) { console.error(error.message); process.exitCode = 1 } else throw error
+    if (error instanceof UserError) { console.error(`${error.message}\n${SUPPORT_LINE}`); process.exitCode = 1 } else {
+      console.error(`Kaloko stopped on an unexpected error (a bug on our side). Send the output below to ${SUPPORT_EMAIL} with the command you ran.`)
+      throw error
+    }
   }
 }

package/src/lib/access.mjs

@@ -167,7 +167,7 @@ export function totp (base32, { step = 30, digits = 6, now = Date.now() } = {})
   let bits = ''
   for (const ch of base32.replace(/[\s=]/g, '').toUpperCase()) {
     const v = alphabet.indexOf(ch)
-    if (v < 0) throw new UserError('The TOTP secret is not base32.')
+    if (v < 0) throw new UserError('The TOTP secret is not base32 (letters A–Z and digits 2–7). Copy the secret again from the setup screen of the account, not the six-digit code.')
     bits += v.toString(2).padStart(5, '0')
   }
   const key = Buffer.from((bits.match(/.{8}/g) || []).map((b) => parseInt(b, 2)))

package/src/lib/apps/drivers.mjs

@@ -78,7 +78,7 @@ function android (cfg, ctx) {
     platform: 'android',
     async open ({ locale, reset, attach = false } = {}) {
       const { stdout } = await adb(['get-state']).catch((e) => { throw new UserError(`No Android device: ${e.message}. Start an emulator or connect a device (adb devices).`) })
-      if (!/device/.test(stdout)) throw new UserError('The Android device is not ready (adb get-state).')
+      if (!/device/.test(stdout)) throw new UserError('The Android device is connected but not ready (adb get-state). Unlock it and allow USB debugging, or wait until the emulator has booted, then run the command again.')
       const dens = (await shell('wm', 'density')).stdout.match(/(\d+)\s*$/m)
       density = dens ? Number(dens[1]) / 160 : 1
       if (!cfg.device) device = (await shell('getprop', 'ro.product.model')).stdout.trim() || 'android'

package/src/lib/apps/webview.mjs

@@ -27,7 +27,7 @@ export function webviewSockets (procNetUnix) {
  * local port and connects Playwright over CDP. Returns { browser, page, pages, close }.
  */
 export async function attachAndroidWebView (cfg, { timeout = 15000 } = {}) {
-  const adb = (args) => run(cfg.adb || 'adb', [...(cfg.serial ? ['-s', cfg.serial] : []), ...args], { timeout: 30000 }).then((r) => r.stdout).catch((e) => { if (e.code === 'ENOENT') throw new UserError('adb is not installed or not on PATH.'); throw e })
+  const adb = (args) => run(cfg.adb || 'adb', [...(cfg.serial ? ['-s', cfg.serial] : []), ...args], { timeout: 30000 }).then((r) => r.stdout).catch((e) => { if (e.code === 'ENOENT') throw new UserError('adb is not installed or not on PATH. Install Android platform-tools (kaloko doctor names the command for this system) and open a new terminal.'); throw e })
   const end = Date.now() + timeout
   let socket = null
   while (!socket && Date.now() < end) {
@@ -43,12 +43,12 @@ export async function attachAndroidWebView (cfg, { timeout = 15000 } = {}) {
   let browser
   try { browser = await chromium.connectOverCDP(`http://127.0.0.1:${port}`, { timeout }) } catch (e) {
     await adb(['forward', '--remove', `tcp:${port}`]).catch(() => {})
-    throw new UserError(`Could not connect to the WebView (${socket.socket}): ${e.message.split('\n')[0]}`)
+    throw new UserError(`Could not connect to the WebView (${socket.socket}): ${e.message.split('\n')[0]}. Bring the app to the front and run the command again.`)
   }
   const pages = browser.contexts().flatMap((c) => c.pages())
   // the visible page first: a WebView app often keeps hidden ones around
   let page = pages[0] || null
   for (const p of pages) { if (await p.evaluate(() => document.visibilityState === 'visible').catch(() => false)) { page = p; break } }
-  if (!page) { await browser.close().catch(() => {}); throw new UserError('The WebView has no page open.') }
+  if (!page) { await browser.close().catch(() => {}); throw new UserError('The WebView has no page open. Open the screen with the WebView in the app, then run the command again.') }
   return { browser, page, pages, socket: socket.socket, close: async () => { await browser.close().catch(() => {}); await adb(['forward', '--remove', `tcp:${port}`]).catch(() => {}) } }
 }

package/src/lib/build.mjs

@@ -4,10 +4,9 @@ import { existsSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { readJson, writeJson } from './util.mjs'
 import { readCaptures, runPaths, listRuns } from './run.mjs'
-import { latestCaptures, evaluationSource, stepIdOf, appliesOn } from './evaluate.mjs'
-import { fieldsOf, DEFAULT_SEMANTIC_SAMPLE } from './stack.mjs'
+import { latestCaptures, evaluationSource, stepIdOf } from './evaluate.mjs'
 import { layout } from './scenario.mjs'
-import { assembleNode, summarize, statusOf, worst } from './manifest-core.mjs'
+import { assembleNode, assembleStack, summarize } from './manifest-core.mjs'
 import { packageRoot } from './schema.mjs'
 import { variantOf } from './dimensions.mjs'
 
@@ -148,53 +147,17 @@ async function runMedia ({ run, entries }) {
  */
 async function buildStack ({ run, node, base, captures, attachments }) {
   const paths = runPaths(run.dir)
-  const fields = fieldsOf(node).map((f) => ({ id: f.id, label: f.label || f.id }))
-  const environment = run.meta?.environment?.name || null
-  const crit = (node.criteria || []).map((c) => ({ id: c.id, text: c.text, type: c.check.type, pack: c.pack || null, ...(appliesOn(c, environment) ? {} : { not_applicable: 'environment' }) }))
-  // criteria limited to other environments do not decide the status of a page
-  const live = new Set(crit.filter((c) => !c.not_applicable).map((c) => c.id))
-  const byItem = new Map()
+  const list = []
   for (const c of captures.filter((x) => x.node === node.id && x.item)) {
     const cap = await readJson(join(run.dir, c.file))
-    const evPath = paths.step(stepIdOf(c), c.locale, c.viewport, 'eval.json')
-    const stored = await readJson(evPath, null)
+    const stored = await readJson(paths.step(stepIdOf(c), c.locale, c.viewport, 'eval.json'), null)
     const ev = stored?.source === evaluationSource(node, cap) ? stored : null
-    let it = byItem.get(c.item)
-    if (!it) { it = { id: c.item, path: cap.item?.path || null, url: cap.url, title: cap.item?.title || cap.fields?.title || cap.metadata?.title || null, fields: cap.fields || {}, captures: {}, results: {}, order: byItem.size }; byItem.set(c.item, it) }
-    ;(it.captures[c.locale] ||= {})[c.viewport] = { png: cap.files.png, thumb: cap.files.thumb || null, html: cap.files.html, url: cap.url, size: cap.size ? [cap.size.width, cap.size.height] : null, boxes: cap.boxes, captured_at: cap.captured_at, console_errors: (cap.console_errors || []).length, console: (cap.console_errors || []).slice(0, 10), overflow: (cap.overflow || []).length, meta: cap.meta, ...(cap.http_status ? { http_status: cap.http_status } : {}), ...(cap.capture?.full_page === false ? { first_screen: true } : {}), eval: ev ? `steps/${stepIdOf(c)}/${c.locale}/${c.viewport}.eval.json` : null }
-    it.results[`${c.locale}|${c.viewport}`] = ev ? Object.fromEntries(ev.criteria.map((r) => [r.id, [r.verdict, r.evidence ? String(r.evidence).slice(0, 200) : null, r.score ?? null]])) : Object.fromEntries(crit.filter((x) => x.type !== 'semantic').map((x) => [x.id, ['not_evaluated', null, null]]))
-    if (!ev) it.stale = true
-  }
-  const items = [...byItem.values()].sort((a, b) => a.order - b.order).map(({ order, ...it }) => {
-    const per = Object.values(it.results)
-    const verdictOf = (id) => worst(per.map((r) => r[id]?.[0]).filter(Boolean))
-    const verdicts = crit.filter((c) => live.has(c.id)).map((c) => verdictOf(c.id)).filter((v) => v !== 'not_reached')
-    const status = statusOf(verdicts, per.length > 0)
-    const by_locale = Object.fromEntries(Object.keys(it.captures).map((l) => [l, statusOf(Object.entries(it.results).filter(([k]) => k.startsWith(`${l}|`)).flatMap(([, r]) => Object.entries(r).filter(([id]) => live.has(id)).map(([, x]) => x[0])), true)]))
-    return { ...it, status, by_locale, fails: crit.filter((c) => live.has(c.id) && verdictOf(c.id) === 'fail').map((c) => c.id), review: crit.filter((c) => live.has(c.id) && ['needs_review', 'not_evaluated'].includes(verdictOf(c.id))).map((c) => c.id) }
-  })
-  const summary = { pass: 0, partial: 0, fail: 0, skip: 0 }
-  for (const it of items) summary[it.status]++
-  const criteria = crit.map((c) => {
-    const counts = {}
-    for (const it of items) { const v = worst(Object.values(it.results).map((r) => r[c.id]?.[0]).filter(Boolean)); if (v !== 'not_reached') counts[v] = (counts[v] || 0) + 1 }
-    return { ...c, counts, verdict: counts.fail ? 'fail' : counts.needs_review ? 'needs_review' : counts.not_evaluated ? 'not_evaluated' : counts.pass ? 'pass' : 'not_reached', by_locale: {} }
-  })
-  const semanticSample = node.items?.semantic_sample ?? DEFAULT_SEMANTIC_SAMPLE
-  const file = `steps/${node.id}/items.json`
-  await writeJson(join(run.dir, file), { schema: 'qawalk.stack.v1', node: node.id, fields, criteria: crit, semantic_sample: semanticSample, items })
-  const thumbOf = (it) => { const c = Object.values(it.captures)[0]; const v = c && Object.values(c)[0]; return v ? v.thumb || v.png : null }
-  const sample = [...items.filter((it) => it.status === 'fail'), ...items.filter((it) => it.status !== 'fail')].slice(0, 4).map((it) => ({ id: it.id, title: it.title, path: it.path, status: it.status, thumb: thumbOf(it) }))
-  const status = !items.length ? 'skip' : summary.fail ? 'fail' : summary.partial || summary.skip ? 'partial' : 'pass'
-  const locales = [...new Set(items.flatMap((it) => Object.keys(it.by_locale)))]
-  const by_locale = Object.fromEntries(locales.map((l) => { const s = items.map((it) => it.by_locale[l]).filter(Boolean); return [l, s.includes('fail') ? 'fail' : s.some((x) => x !== 'pass') ? 'partial' : 'pass'] }))
-  const src = node.items || {}
-  return {
-    ...base, status, by_locale, captures: {}, criteria, semantic: {}, metadata: {}, session: node.session || null,
-    execution: node.execution ? { strategy: node.execution.strategy, instructions: node.execution.instructions } : { strategy: 'playwright', instructions: 'Open every page of the stack and capture it.' },
-    attachments: attachments.filter((a) => a.node === node.id && a.kind !== 'focus').map((a) => ({ type: a.kind, title: a.title, file: a.file, locale: a.locale })),
-    stack: { count: items.length, items: file, summary, fields, sample, semantic_sample: semanticSample, source: ['urls', 'file', 'sitemap', 'crawl', 'script'].find((k) => src[k]) || null, stale: items.filter((it) => it.stale).length }
+    // a variant of a design stack (#61) opens live in the lightbox: its page in the step's revision
+    list.push({ item: c.item, locale: c.locale, viewport: c.viewport, cap, ev, files: { png: cap.files.png, thumb: cap.files.thumb || null, html: cap.files.html, eval: `steps/${stepIdOf(c)}/${c.locale}/${c.viewport}.eval.json` }, ...(cap.live ? { live: cap.live } : {}) })
   }
+  const { node: out, index, file } = assembleStack({ node, base, environment: run.meta?.environment?.name || null, captures: list, attachments })
+  await writeJson(join(run.dir, file), index)
+  return out
 }
 
 /**

package/src/lib/capture.mjs

@@ -165,7 +165,7 @@ export async function captureStep ({ page, node, locale, viewports, run, console
         }
       }
       // the step spec (Dev mode, `kaloko spec`, drift): elements with roles, names and styles mapped to the tokens
-      if (probeArgs(node, maxChars, designSummary).design && !item) result.spec = await stepSpec(page, tokens, scope?.variants?.[viewport]?.color_scheme || null)
+      if (probeArgs(node, maxChars, designSummary).design && !item) result.spec = await stepSpec(page, tokens, scope?.variants?.[viewport]?.token_mode || scope?.variants?.[viewport]?.color_scheme || null)
       // regions the scenario ignores in pixel comparisons (#20), as page rectangles of this capture
       const ignore = await resolveIgnore(page, node, locale, viewport)
       // what moves while the page sits still (walk --stability N): repeated screenshots, compared here

package/src/lib/changelog.mjs

@@ -8,7 +8,7 @@ import { promisify } from 'node:util'
 import { join, resolve, relative, dirname, basename } from 'node:path'
 import { UserError, sha256 } from './util.mjs'
 import { repoSlug } from './git.mjs'
-import { cleanVersion, compareVersions, tagFor, versionOfTag, latestVersionIn, sectionOf, applyDraft, finalizeRelease, draftEntry, groupsMarkdown, parseEntry, findStepRefs, CHANGELOG_SKELETON } from './changelog-core.mjs'
+import { cleanVersion, compareVersions, tagFor, versionOfTag, latestVersionIn, sectionOf, applyDraft, finalizeRelease, draftEntry, parseEntry, findStepRefs, CHANGELOG_SKELETON } from './changelog-core.mjs'
 
 const run = promisify(execFile)
 async function out (cmd, args, cwd, timeout = 20000) {
@@ -236,7 +236,7 @@ export async function releaseProduct ({ root, config, product, version = null, d
   const src = await detectVersionSource(root, product)
   const v = cleanVersion(version || src.version || '')
   if (!v) throw new UserError(`Which version? Pass it (kaloko release 2.4.0); ${src.source === 'git-tag' ? `no tag matches ${src.pattern}` : `${src.path || src.source} names none`}.`)
-  if (!/^[0-9A-Za-z][0-9A-Za-z.+-]{0,79}$/.test(v)) throw new UserError(`Not a version: ${v}`)
+  if (!/^[0-9A-Za-z][0-9A-Za-z.+-]{0,79}$/.test(v)) throw new UserError(`${v} is not a version Kaloko can use: letters, digits, dots, + and -, at most 80 characters (e.g. 2.4.0).`)
   const notes = []
   if (src.version && src.version !== v && src.source !== 'git-tag' && src.source !== 'semantic-release') notes.push(`${src.tool || src.source} (${src.path}) says ${src.version}; recording ${v} as you asked.`)
   const file = changelogFile(root, product)