kaloko 0.8.0 → 0.9.0

package/README.md

@@ -182,7 +182,9 @@ npx kaloko import walkthrough/ --adhoc      # a Cursor or Antigravity walkthroug
 lays screenshots, Playwright reports and traces out as a run: matched to the
 scenario's steps (by step id in `steps.json`, URL or title), or as an ad-hoc
 flow when there is no scenario. Build and share it like any run. When something does not work (Chrome,
-token, environment URL, evaluator key), `npx kaloko doctor` says what to fix.
+token, environment URL, evaluator key), `npx kaloko doctor` says what to fix, and
+`npx kaloko doctor --fix` installs a missing browser, creates missing folders and fills in `org:` from your token.
+Every error the CLI prints says what to do next; if you are still stuck, write to support@sinfin.cz.
 
 ## Review only what changed
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "See what your AI agents built: every screen, language and device walked, assessed and approved on one canvas.",
   "keywords": [
     "qa",

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'
@@ -94,7 +94,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)
@@ -449,7 +451,7 @@ 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
@@ -655,6 +657,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 +674,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`)
@@ -2106,9 +2110,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 +2124,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 +2203,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 +2224,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 +2240,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 +2288,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 +2316,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 +2330,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 +2364,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/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)

package/src/lib/design-export.mjs

@@ -89,7 +89,7 @@ async function runIdOf ({ client, org, scenarioId, ref, branch }) {
   }
   if (/^v\d+$/.test(ref)) {
     const v = (await client.request('GET', `/orgs/${org}/scenarios/${enc(scenarioId)}/versions`)).find((x) => String(x.version) === ref.slice(1))
-    if (!v) throw new UserError(`${scenarioId} has no version ${ref}.`)
+    if (!v) throw new UserError(`${scenarioId} has no version ${ref}. kaloko history lists its versions.`)
     return v.id
   }
   return ref
@@ -111,7 +111,7 @@ export async function exportDesign ({ config, scenarioId, client, ref = 'design'
   const sink = exportSink(out)
   const fileOf = async (path) => {
     const res = draft ? await fetch(manifest.files_base + path) : await client.fetch(`/orgs/${org}/runs/${runId}/files/${path.split('/').map(enc).join('/')}`)
-    if (!res.ok) throw new UserError(`${path}: HTTP ${res.status}`)
+    if (!res.ok) throw new UserError(`Downloading ${path} failed (HTTP ${res.status}). Run the export again; if it keeps failing, the file may have expired with its run.`)
     return Buffer.from(await res.arrayBuffer())
   }
   // the live files keep the design folder layout: links between steps work from disk exactly as in the folder

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

@@ -288,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/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/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]

package/src/lib/stack.mjs

@@ -66,7 +66,7 @@ export async function resolveItems ({ node, base, page, scenarioDir, env, locale
     if (first.index) { locs = []; for (const u of first.locs.slice(0, 50)) locs.push(...sitemapLocs(await get(u)).locs) }
     raw = locs.map((u) => ({ path: u }))
   } else if (src.crawl) {
-    if (!page) throw new UserError('items.crawl needs a browser page.')
+    if (!page) throw new UserError('items.crawl needs the browser. Walk the step with kaloko walk (not offline), or list the pages with items.file or items.sitemap.')
     let url = toUrl(src.crawl.from)
     for (let i = 0; i < (src.crawl.pages || 1) && url; i++) {
       await page.goto(url, { waitUntil: 'domcontentloaded' })
@@ -129,3 +129,13 @@ export function readFields (specs) {
   }
   return out
 }
+
+/** "about 4 min left" after `done` of `total` pages took `ms`; '' before the first page or after the last. */
+export function timeLeft (done, total, ms) {
+  if (!(done > 0) || done >= total || !(ms >= 0)) return ''
+  const s = Math.round((ms / done) * (total - done) / 1000)
+  if (s < 60) return `about ${Math.max(5, Math.round(s / 5) * 5)} s left`
+  if (s < 3600) return `about ${Math.round(s / 60)} min left`
+  const h = Math.floor(s / 3600); const m = Math.round((s % 3600) / 60)
+  return `about ${h} h${m ? ` ${m} min` : ''} left`
+}

package/src/lib/util.mjs

@@ -67,6 +67,12 @@ export function globToRegExp (glob) {
 
 export class UserError extends Error {}
 
+/** Every CLI error ends with a way to a person (docs/HARDENING.md phase 6, item 12). */
+export const SUPPORT_EMAIL = 'support@sinfin.cz'
+/** No `org:` in the config: where the slug comes from. */
+export const NO_ORG = 'No organization in kaloko.config.yml. Add org: <slug> (the part after kaloko.app/ when you are signed in), or run kaloko login.'
+export const SUPPORT_LINE = `Stuck? Write to ${SUPPORT_EMAIL} with the command you ran and this message.`
+
 /**
  * Tracks consecutive step failures per session. When `limit` steps in a row fail with the same first
  * error line, the remaining steps of that session are almost certainly failing on a shared

package/src/lib/video.mjs

@@ -188,7 +188,12 @@ function install () {
         if (this.enc) {
           const f = new VideoFrame(this.canvas, { timestamp: Math.round(tk.t * 1000), duration: Math.round(1e6 / c.fps) })
           this.enc.encode(f, { keyFrame: this.n % c.keyEvery === 0 }); f.close(); this.n++
-          while (this.enc.encodeQueueSize > 6) await new Promise((resolve) => setTimeout(resolve, 2))
+          // a stalled encoder (seen under heavy load) must not hold the walk: after 20 s the recording gives up
+          const until = Date.now() + 20000
+          while (this.enc && this.enc.encodeQueueSize > 6) {
+            if (Date.now() > until) { this.error = 'the video encoder stopped responding'; try { this.enc.close() } catch {} this.enc = null; break }
+            await new Promise((resolve) => setTimeout(resolve, 2))
+          }
         }
         if (tk.preview) {
           this.pg.drawImage(this.canvas, 0, 0, c.pw, c.ph)
@@ -199,7 +204,11 @@ function install () {
       return { ...out, chunks: this.chunks.splice(0), error: this.error }
     },
     async finish () {
-      if (this.enc) { try { await this.enc.flush() } catch (e) { this.error = String(e?.message || e) } this.enc.close() }
+      if (this.enc) {
+        // flush has no time limit of its own: a stalled encoder ends the recording with an error instead of hanging
+        try { await Promise.race([this.enc.flush(), new Promise((resolve, reject) => setTimeout(() => reject(new Error('the video encoder did not finish within 30 s')), 30000))]) } catch (e) { this.error = String(e?.message || e) }
+        try { this.enc.close() } catch {}
+      }
       for (const bm of this.bitmaps.values()) bm.close()
       this.bitmaps.clear()
       return { chunks: this.chunks.splice(0), error: this.error }

package/src/lib/vision.mjs

@@ -120,7 +120,7 @@ export function hostedVisionSender (config, report) {
     try { if (!client) { const { service } = await import('./service.mjs'); client = service(config) } } catch { return { skipped: 'no vision key (ANTHROPIC_API_KEY) and no service token (KALOKO_TOKEN) for hosted evaluation' } }
     try { return { response: await client.request('POST', `/orgs/${config.org}/semantic/vision`, payload) } } catch (e) {
       const m = String(e.message || e)
-      if (/HTTP (402|403|404|503)/.test(m)) { report.visionStop = m.replace(/^.*HTTP \d+: /, ''); return { skipped: report.visionStop } }
+      if (/HTTP (402|403|404|503)/.test(m)) { report.visionStop = e.serviceMessage ?? m.replace(/^.*HTTP \d+: /, ''); return { skipped: report.visionStop } }
       return { error: m }
     }
   }

package/viewer/index.html

@@ -14,7 +14,7 @@
 @font-face{font-family:"Instrument Sans Fallback";src:local("Arial Bold"),local("Arial");font-weight:700;size-adjust:98.1%;ascent-override:99%;descent-override:25%;line-gap-override:0%}
 :root{
   --ground:#ecece8; --dots:#c9c9c3; --panel:#ffffff; --panel-2:#f5f5f2;
-  --ink:#151514; --muted:#6a6a64; --line:#d7d7d1; --line-strong:#151514;
+  --ink:#151514; --muted:#6a6a64; --line:#d7d7d1; --line-strong:#151514; --field:#7a7a73;
   --accent:#ffe452; --accent-ink:#151514; --focus:#151514;
   --pass:#1d8249; --fail:#c8102e; --partial:#b86e00; --skip:#8d8d86;
   --pass-bg:#e3f3e9; --fail-bg:#fbe5e8; --partial-bg:#fbf0dc; --skip-bg:#ececea;
@@ -26,7 +26,7 @@
 @media (prefers-color-scheme:dark){:root:not([data-theme="light"]){
   color-scheme:dark;
   --ground:#151514; --dots:#2c2c29; --panel:#1f1f1d; --panel-2:#262624;
-  --ink:#f0f0ec; --muted:#9d9d96; --line:#35352f; --line-strong:#f0f0ec;
+  --ink:#f0f0ec; --muted:#9d9d96; --line:#35352f; --field:#7d7d76; --line-strong:#f0f0ec;
   --pass:#52c784; --fail:#ff6070; --partial:#f0a83c; --skip:#8d8d86;
   --pass-bg:#18311f; --fail-bg:#3a1a1f; --partial-bg:#372a14; --skip-bg:#2a2a27;
   --pass-ink:#52c784; --fail-ink:#ff6070; --partial-ink:#f0a83c; --skip-ink:#a9a9a2;
@@ -35,7 +35,7 @@
 :root[data-theme="dark"]{
   color-scheme:dark;
   --ground:#151514; --dots:#2c2c29; --panel:#1f1f1d; --panel-2:#262624;
-  --ink:#f0f0ec; --muted:#9d9d96; --line:#35352f; --line-strong:#f0f0ec;
+  --ink:#f0f0ec; --muted:#9d9d96; --line:#35352f; --field:#7d7d76; --line-strong:#f0f0ec;
   --pass:#52c784; --fail:#ff6070; --partial:#f0a83c; --skip:#8d8d86;
   --pass-bg:#18311f; --fail-bg:#3a1a1f; --partial-bg:#372a14; --skip-bg:#2a2a27;
   --pass-ink:#52c784; --fail-ink:#ff6070; --partial-ink:#f0a83c; --skip-ink:#a9a9a2;
@@ -124,6 +124,8 @@ svg.i{width:14px;height:14px;fill:none;stroke:currentColor;stroke-width:1.7;stro
 .picker .kchip{font-size:10.5px;font-weight:700;letter-spacing:.05em;text-transform:uppercase;padding:2px 6px;border-radius:4px;background:var(--accent);color:var(--accent-ink);flex:none}
 .picker .kchip--flow{background:var(--ink);color:var(--panel)}
 .picker kbd,.kbd{font-family:var(--mono);font-size:10.5px;border:1px solid var(--line);border-bottom-width:2px;border-radius:4px;padding:0 5px;color:var(--muted);flex:none}
+/* a key inside a button takes the button's text colour: grey on the yellow primary button is unreadable */
+.btn .kbd{color:inherit}
 .tog{width:30px;height:30px;display:inline-grid;place-items:center;border-radius:6px;border:1px solid var(--line);background:var(--panel)}
 .tog[aria-pressed="true"]{background:var(--ink);color:var(--panel);border-color:var(--ink)}
 .tog svg.i{width:16px;height:16px}
@@ -295,6 +297,9 @@ table.runs{border-collapse:collapse;width:100%;font-size:12.5px}
 
 .toast{position:fixed;left:50%;bottom:22px;transform:translateX(-50%);background:var(--ink);color:var(--panel);padding:8px 14px;border-radius:999px;font-size:13px;z-index:30;box-shadow:var(--shadow)}
 .sess-lost{position:fixed;left:50%;top:16px;transform:translateX(-50%);z-index:60;display:flex;flex-wrap:wrap;gap:8px 12px;align-items:center;background:var(--panel);color:var(--ink);border:1px solid var(--fail);border-radius:10px;padding:10px 14px;font-size:13px;box-shadow:var(--shadow);width:max-content;max-width:calc(100vw - 32px)}
+.net-bar{position:fixed;left:50%;top:16px;transform:translateX(-50%);z-index:59;display:flex;flex-wrap:wrap;gap:8px 12px;align-items:center;background:var(--panel);color:var(--ink);border:1px solid var(--partial);border-radius:10px;padding:10px 14px;font-size:13px;box-shadow:var(--shadow);width:max-content;max-width:calc(100vw - 32px)}
+.net-bar .note{color:var(--muted)}
+.sess-lost ~ .net-bar{top:76px}
 
 @media (max-width:1100px){
   .main{grid-template-columns:minmax(0,1fr)}
@@ -784,7 +789,7 @@ details summary{cursor:pointer;font-size:12.5px;font-weight:500}
 .c-note{margin:4px 0 2px;font-size:13.5px;overflow-wrap:anywhere}.c-at{color:var(--ink);background:color-mix(in srgb,var(--accent,#ffe452) 45%,transparent);border-radius:3px;padding:0 2px;font-weight:600}
 .c-acts{display:flex;gap:10px;font-size:12px}.c-acts button,.linkish{all:unset;cursor:pointer;color:var(--muted);text-decoration:underline;text-underline-offset:3px}.c-acts button:hover,.linkish:hover{color:var(--ink)}
 .c-pin{all:unset;cursor:pointer;min-width:18px;height:18px;padding:0 4px;border-radius:9px 9px 9px 2px;background:#e4572e;color:#fff;font:600 10.5px/18px system-ui,sans-serif;text-align:center}
-.c-compose{margin-top:6px}.c-compose .c-text{width:100%;box-sizing:border-box;font:inherit;padding:8px;border:1px solid var(--line);border-radius:6px;background:var(--panel);color:var(--ink);margin:4px 0 8px;resize:vertical}
+.c-compose{margin-top:6px}.c-compose .c-text{width:100%;box-sizing:border-box;font:inherit;padding:8px;border:1px solid var(--field,var(--line));border-radius:6px;background:var(--panel);color:var(--ink);margin:4px 0 8px;resize:vertical}
 .c-hint{margin-left:auto;font-size:11.5px}@media (hover:none) and (pointer:coarse){.c-hint{display:none}}.c-pinrow{display:flex;gap:8px;align-items:center;flex-wrap:wrap;font-size:12.5px}.c-pinned{display:inline-flex;gap:5px;align-items:center}.c-pinbtn[aria-pressed="true"]{background:var(--ink);color:var(--panel)}
 .c-tabs{margin:0 0 10px}.cmt{display:inline-flex;align-items:center;gap:3px;font:600 11px/1 system-ui,sans-serif;color:var(--ink);padding:2px 6px;border-radius:999px;background:color-mix(in srgb,var(--partial) 22%,transparent)}.cmt .i{width:12px;height:12px}
 .lb__img.is-pinning,.lb__img.is-pinning img{cursor:crosshair}.pinmark.pin-xy{border:0;cursor:pointer;transform:translate(-2px,-100%)}.pinmark.pin-xy.is-done{background:#8a8a84}.pinmark.pin-xy.is-new{background:var(--ink)}.pinmark.flash{animation:pinflash 1s 2}
@@ -869,6 +874,10 @@ details summary{cursor:pointer;font-size:12.5px;font-weight:500}
 .rvm__side{overflow:auto;background:var(--panel);border-left:1px solid var(--line)}
 .rvm__foot{display:flex;align-items:center;gap:8px;flex-wrap:wrap;padding:10px 16px calc(10px + env(safe-area-inset-bottom));background:var(--panel);border-top:1px solid var(--line)}
 .rvm__foot .btn .kbd,.rvm__top .kbd{margin-left:4px}
+.rvm__flash{flex:1 1 100%;margin:0;padding:8px 12px;border-radius:8px;font-size:14px;animation:rvflash .25s ease-out}
+.rvm__flash--approved{background:var(--pass-bg);color:var(--pass-ink)}.rvm__flash--returned{background:var(--fail-bg);color:var(--fail-ink)}
+@keyframes rvflash{from{opacity:0;transform:translateY(6px)}}
+@media (prefers-reduced-motion:reduce){.rvm__flash{animation:none}}
 .rvm__why{display:flex;flex-wrap:wrap;gap:4px;margin-top:8px}
 .rvm__dec{display:grid;gap:6px}
 .rvm__dec p{margin:0}
@@ -883,6 +892,8 @@ details summary{cursor:pointer;font-size:12.5px;font-weight:500}
 #rvBtn .rv-count{display:inline-grid;place-items:center;min-width:18px;height:18px;padding:0 5px;margin-left:4px;border-radius:999px;background:var(--ink);color:var(--panel);font-size:11px;font-weight:600}
 .badge.rv-carry{margin-left:auto}
 @media (max-width:900px){.rvm__body{grid-template-columns:1fr;grid-template-rows:minmax(220px,55%) 1fr}.rvm__side{border-left:0;border-top:1px solid var(--line)}.rvm__stage{padding:12px}.rvm__bar{width:72px}.rvm__keys{display:none}}
+/* a phone: the decisions sit in the bottom row, under the thumb (Approve on the right, wide), moving on above them */
+@media (max-width:560px){.rvm__foot--act{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));grid-template-areas:"flash flash flash" "prev cmt next" "ret ok ok"}.rvm__foot--act .rvm__flash{grid-area:flash}.rvm__foot--act #rvPrev{grid-area:prev}.rvm__foot--act #rvCmt{grid-area:cmt}.rvm__foot--act #rvNext{grid-area:next}.rvm__foot--act #rvRet{grid-area:ret}.rvm__foot--act #rvOk{grid-area:ok}.rvm__foot--act #rvRet,.rvm__foot--act #rvOk{min-height:52px;font-size:16px}.rvm__foot .btn{min-height:44px}.rvm__foot--act .btn{min-width:0}}
 @media (max-width:560px){.rvm__foot{gap:6px;padding:8px 10px calc(8px + env(safe-area-inset-bottom))}.rvm__foot .btn{flex:1 1 auto;justify-content:center;padding:9px 8px}.rvm__foot .spacer{display:none}.rvm__top{padding:8px 10px}.rvm__top .brand small{display:none}}
 @media (hover:none) and (pointer:coarse){.rvm .kbd,.rvm__keys{display:none}}
 @media (max-width:1400px){#rvBtn span[data-t]{display:none}#rvBtn{padding:5px 8px}}
@@ -1102,6 +1113,9 @@ Object.assign(I18N.cs, { devMode:'Dev mode', devTab:'Dev', devTitle:'Míry, toke
 Object.assign(I18N.en, { devMode:'Dev mode', devTab:'Dev', devTitle:'Measurements, tokens and states of elements for development', devTabEl:'Element', devTabTokens:'Tokens', devEmpty:'Hover an element in the preview and click it. Shift + arrows move through the element tree; hold Alt to see the distances to another element.', devStart:'Select the main content', devNavLabel:'Move through elements', navParent:'Parent', navChild:'Child', navPrev:'Previous', navNext:'Next', g_type:'Typography', g_color:'Colors', g_space:'Spacing', g_size:'Size', g_shape:'Shape', g_layout:'Layout', notToken:'not a token', nearest:'nearest', typedRaw:'The CSS has this value typed raw although a token exists; use the custom property.', typedRawShort:'typed raw', copyTokenPath:'Copy the token path', contrast:'Contrast', aaPass:'passes AA', aaFail:'fails AA', aaNeed:'needs', largeText:'large text', contrastApprox:'There is an image behind the text; the contrast is approximate.', states:'States', stDefault:'default', stNone:'The page styles define no states for this element.', changedInState:'Highlighted values change in this state.', distances:'Distances', toParent:'To the parent', toTarget:'To', measure:'Measure', measureHint:'Hold Alt and hover another element, or turn on Measure and tap it.', assets:'Images and icons', download:'Download', assetFail:'The file could not be downloaded.', copyCssVars:'Copy CSS with variables', copyTokens:'Copy tokens (JSON)', copyPrompt:'Copy prompt for an agent', copyLine:'Copy the prompt line for this value', pinFromDev:'Comment on this element', tokUsed:'Used on this step', tokOff:'Values outside the token set', tokHard:'Typed raw in the CSS instead of a token', tokUnused:'Not used', tokNone:'This step has no token set (tokens.json).', tokHlN:'Elements highlighted:', tokHint:'Click a token to highlight the elements that use it.', devShotNote:'Measurements and tokens come from the screenshot as the CLI captured it; states and image downloads need the live page.', devNoSpec:'This capture has no spec. Walk the step again with the current CLI (kaloko walk).', devLocalLive:'From disk, Dev mode reads the screenshot; the live page is measured on kaloko.app.', devAgentHint:'An agent gets the same: kaloko spec %N or MCP get_step_spec.', devLoading:'Loading…', keyDev:'Dev mode in the step detail: measurements, tokens and states of elements (M measures, Shift + arrows move through elements)', promptHead:'Build %E as approved in Kaloko (step %S).', promptUse:'Use token %T for the %W.', promptOff:'%P %V is not a token; the nearest is %T. Use the raw value only if the designer agrees.', promptOffNone:'%P %V is not a token.', promptSpec:'Spec of the whole step: kaloko spec %N' });
 Object.assign(I18N.cs, { sessionLost:'Přihlášení vypršelo. Přihlaste se znovu, rozepsaný text tu na vás počká.', signInAgain:'Přihlásit se znovu' });
 Object.assign(I18N.en, { sessionLost:'Your session has expired. Sign in again; what you were writing waits here.', signInAgain:'Sign in again' });
+// the connection drops or the service fails while the canvas is open (NET, netSend)
+Object.assign(I18N.cs, { netOffline:'Jste offline. Co napíšete, tu počká, než se připojení vrátí.', netOfflineN:(n) => `Jste offline. ${n === 1 ? '1 změna čeká' : n < 5 ? `${n} změny čekají` : `${n} změn čeká`} tady a odešle se, až se připojení vrátí.`, netFailedN:(n, why) => `Kaloko ${n === 1 ? '1 změnu' : n < 5 ? `${n} změny` : `${n} změn`} zatím neuložilo (${why}). Nic se neztratilo.`, netNoAnswer:'služba neodpovídá', netError:(c) => c === 429 ? 'příliš mnoho požadavků' : `chyba ${c}`, netAgainIn:(s) => `Zkusím to znovu za ${s} s.`, netRetry:'Zkusit znovu', netSending:'Odesílám…', netBack:'Připojení je zpět, všechno se odeslalo.', netLeave:'Některé změny ještě nejsou odeslané.' });
+Object.assign(I18N.en, { netOffline:'You are offline. What you write waits here until the connection is back.', netOfflineN:(n) => `You are offline. ${n === 1 ? '1 change waits here and goes' : `${n} changes wait here and go`} out when the connection is back.`, netFailedN:(n, why) => `Kaloko has not saved ${n === 1 ? '1 change' : `${n} changes`} yet (${why}). Nothing is lost.`, netNoAnswer:'the service does not answer', netError:(c) => c === 429 ? 'too many requests' : `error ${c}`, netAgainIn:(s) => `Trying again in ${s} s.`, netRetry:'Try again', netSending:'Sending…', netBack:'Back online; everything has been sent.', netLeave:'Some changes have not been sent yet.' });
 // back after signing in again: the session expired on the canvas (sessionLost), the server kept the path, but the
 // sign-in mail cannot carry the fragment (the open step, the comments), so the canvas stored it for this moment
 (() => { try { const r = JSON.parse(localStorage.getItem('qawalk-return') || 'null'); if (!r) return; localStorage.removeItem('qawalk-return'); if (r.path === location.pathname && r.hash && !location.hash && Date.now() - r.at < 864e5) history.replaceState(null, '', location.pathname + location.search + r.hash); } catch {} })();
@@ -1431,7 +1445,8 @@ function commentsBase (scope) {
   return scope === 'flow' ? `${a.api}/orgs/${a.org}/scenarios/${encodeURIComponent(RUN.scenario.id)}/comments` : `${a.api}/orgs/${a.org}/runs/${a.run}/comments`;
 }
 async function cApi (scope, path, method, body) {
-  const res = await fetch(commentsBase(scope) + path, { method, credentials: 'same-origin', headers: body ? { 'Content-Type': 'application/json' } : {}, body: body ? JSON.stringify({ ...body, ...(isDraft() ? { branch: RUN.draft.branch } : {}) }) : undefined });
+  const init = { method, credentials: 'same-origin', headers: body ? { 'Content-Type': 'application/json' } : {}, body: body ? JSON.stringify({ ...body, ...(isDraft() ? { branch: RUN.draft.branch } : {}) }) : undefined };
+  const res = method === 'GET' ? await fetch(commentsBase(scope) + path, init) : await netSend(commentsBase(scope) + path, init, method === 'POST' && !path ? { find: commentSent(scope, body) } : {});
   if (res.status === 401) throw sessionLost();
   const data = await res.json().catch(() => ({}));
   if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
@@ -3780,13 +3795,88 @@ function sessionLost () {
   return new Error(T('sessionLost'));
 }
 async function apiJson (method, url, body) {
-  const res = await fetch(url, { method, credentials: 'same-origin', headers: body ? { 'Content-Type': 'application/json' } : {}, body: body ? JSON.stringify(body) : undefined });
+  const init = { method, credentials: 'same-origin', headers: body ? { 'Content-Type': 'application/json' } : {}, body: body ? JSON.stringify(body) : undefined };
+  const res = method === 'GET' ? await fetch(url, init) : await netSend(url, init);
   if (res.status === 401) throw sessionLost();
   const data = await res.json().catch(() => ({}));
   if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
   return data;
 }
 
+/**
+ * Writes survive a dropped connection. A request that cannot reach the service (offline, a dropped connection) or that
+ * the service could not handle (5xx, 429, 408) waits in a queue the bar at the top names; it goes out again when the
+ * browser is back online, on a timer (Retry-After when the service sends one) or on "Try again". The caller's promise
+ * only settles with a real answer, so its button stays busy and nothing is lost silently; leaving the page while
+ * something waits asks first. `find` looks for what the first attempt may already have created (a new comment), so a
+ * request that did arrive is not sent twice.
+ */
+const NET = { pending: [], timer: null, tick: null, was: false };
+const netTrouble = (res) => !res || res.status >= 500 || res.status === 429 || res.status === 408;
+async function netSend (url, init, { find } = {}) {
+  const started = Date.now();
+  for (let attempt = 0; ; attempt++) {
+    if (attempt && find) {
+      let hit;
+      try { hit = await find(started); } catch { hit = undefined; }
+      if (hit) return new Response(JSON.stringify(hit), { status: 200, headers: { 'Content-Type': 'application/json' } });
+      if (hit === undefined) { await netWait({ status: 0, attempt }); continue; } // cannot look yet: wait again
+    }
+    let res = null;
+    if (navigator.onLine !== false) { try { res = await fetch(url, init); } catch { res = null; } }
+    if (!netTrouble(res)) { if (NET.was && !NET.pending.length) { NET.was = false; toast(T('netBack')); } return res; }
+    const after = Number(res?.headers.get('retry-after'));
+    await netWait({ status: res?.status || 0, attempt, after: Number.isFinite(after) && after > 0 ? Math.min(after, 300) : 0 });
+  }
+}
+function netWait (entry) {
+  return new Promise((resolve) => {
+    entry.go = () => { NET.pending = NET.pending.filter((x) => x !== entry); resolve(); };
+    // the service failed or did not answer: try again by itself a few times (3, 10, 30 s), then wait for a person
+    const delay = entry.after ? entry.after * 1000 : [3000, 10000, 30000][entry.attempt];
+    entry.at = navigator.onLine === false || !delay ? 0 : Date.now() + delay;
+    NET.pending.push(entry); NET.was = true;
+    netBar();
+  });
+}
+/** Sends everything waiting now (back online, "Try again", or a timer that came due). */
+function netFlush (only) {
+  const due = NET.pending.filter((x) => !only || only(x));
+  for (const x of due) x.go();
+  netBar();
+}
+function netBar () {
+  clearTimeout(NET.timer); clearInterval(NET.tick); NET.tick = null;
+  const offline = navigator.onLine === false;
+  const n = NET.pending.length;
+  let bar = $('netBar');
+  if (!n && !offline) { bar?.remove(); return; }
+  if (!bar) { document.body.insertAdjacentHTML('beforeend', '<div id="netBar" class="net-bar" role="status" aria-live="polite"><span class="net-bar__msg"></span><span class="note net-bar__when"></span><button type="button" class="btn net-bar__retry"></button></div>'); bar = $('netBar'); bar.querySelector('.net-bar__retry').onclick = () => { bar.querySelector('.net-bar__when').textContent = T('netSending'); netFlush(); }; }
+  const last = NET.pending.at(-1);
+  bar.querySelector('.net-bar__msg').textContent = offline ? (n ? T('netOfflineN')(n) : T('netOffline')) : T('netFailedN')(n, last?.status ? T('netError')(last.status) : T('netNoAnswer'));
+  const btn = bar.querySelector('.net-bar__retry'); btn.textContent = T('netRetry'); btn.hidden = !n;
+  const next = offline ? 0 : Math.min(...NET.pending.map((x) => x.at || Infinity));
+  const when = bar.querySelector('.net-bar__when');
+  const show = () => { const s = Math.max(1, Math.ceil((next - Date.now()) / 1000)); when.textContent = T('netAgainIn')(s); };
+  if (Number.isFinite(next) && next > 0) {
+    show(); NET.tick = setInterval(show, 1000);
+    NET.timer = setTimeout(() => netFlush((x) => x.at && x.at <= Date.now() + 50), Math.max(0, next - Date.now()));
+  } else when.textContent = '';
+}
+addEventListener('online', () => { if (NET.pending.length) netFlush(); else netBar(); });
+addEventListener('offline', () => { if (APP()) netBar(); });
+addEventListener('beforeunload', (e) => { if (NET.pending.length) { e.preventDefault(); e.returnValue = T('netLeave'); return T('netLeave'); } });
+/** A new comment the first attempt may have created already: same step, text, status and thread, by this person. */
+function commentSent (scope, body) {
+  return async (since) => {
+    const me = APP()?.user?.email;
+    const res = await fetch(commentsBase(scope) + (isDraft() ? branchQ() : ''), { credentials: 'same-origin' });
+    if (!res.ok) return undefined;
+    const list = await res.json();
+    return (Array.isArray(list) ? list : []).find((c) => c.node_id === body.node_id && (c.note || '') === (body.note || '') && (c.status || 'comment') === (body.status || 'comment') && (c.parent_id || null) === (body.parent_id || null) && (!me || c.email === me) && Date.parse(c.created_at) >= since - 120000) || null;
+  };
+}
+
 // the draft is live: re-read it when someone (a person or an agent) changes it
 let reloadTimer = null;
 function reloadDraftSoon () { clearTimeout(reloadTimer); reloadTimer = setTimeout(reloadDraft, 350); }
@@ -4784,7 +4874,7 @@ Object.assign(I18N.cs, {
   rvCarriedWhy: 'Snímky i kritéria jsou stejné jako v přijatém běhu a automatické kontroly prošly.',
   rvRevoke: 'Zrušit převzaté schválení', rvRevoked: 'Převzaté schválení je zrušené; krok čeká na kontrolu.',
   rvUnconfirmed: 'Rozhodnutí agenta nebo tokenu; za rozhodnutí člověka se nepočítá', rvChangedIn: 'Změněné snímky', rvCritChanged: 'Kritéria se od přijatého běhu změnila.',
-  rvApprovedToast: 'Schváleno', rvReturnedToast: 'Vráceno autorovi běhu', rvReadOnly: 'Jen ke čtení', rvLocal: 'Rozhodovat se dá na kaloko.app, až se běh nasdílí.',
+  rvApprovedToast: 'Schváleno', rvFlashNext: 'další:', rvReturnedToast: 'Vráceno autorovi běhu', rvReadOnly: 'Jen ke čtení', rvLocal: 'Rozhodovat se dá na kaloko.app, až se běh nasdílí.',
   rvDone: 'Všechny kroky jsou rozhodnuté', rvLeft: (n) => `Na rozhodnutí ${n === 1 ? 'čeká 1 krok' : n < 5 ? `čekají ${n} kroky` : `čeká ${n} kroků`}`,
   rvNothing: 'Nic nečeká na člověka: kroky prošly a od přijatého běhu se nezměnily.', rvSumApproved: 'schváleno', rvSumReturned: 'vráceno', rvSumClear: 'beze změny a bez připomínek',
   rvCarriedTitle: 'Převzatá schválení', rvCarriedLead: 'Tyto kroky vypadají stejně jako v přijatém běhu a jejich automatické kontroly prošly. U každého je, kdo ho schválil.',
@@ -4805,14 +4895,14 @@ Object.assign(I18N.en, {
   rvCarriedWhy: 'The screenshots and criteria are the same as in the accepted run and the automatic checks passed.',
   rvRevoke: 'Revoke the carried approval', rvRevoked: 'Carried approval revoked; the step waits for review.',
   rvUnconfirmed: 'An agent’s or token’s decision; it does not count as a person’s', rvChangedIn: 'Changed screenshots', rvCritChanged: 'The criteria changed since the accepted run.',
-  rvApprovedToast: 'Approved', rvReturnedToast: 'Returned to the author of the run', rvReadOnly: 'Read only', rvLocal: 'Decisions are made on kaloko.app once the run is shared.',
+  rvApprovedToast: 'Approved', rvFlashNext: 'next:', rvReturnedToast: 'Returned to the author of the run', rvReadOnly: 'Read only', rvLocal: 'Decisions are made on kaloko.app once the run is shared.',
   rvDone: 'Every step is decided', rvLeft: (n) => `${n} step${n === 1 ? '' : 's'} still wait${n === 1 ? 's' : ''} for a decision`,
   rvNothing: 'Nothing waits for a person: the steps passed and did not change since the accepted run.', rvSumApproved: 'approved', rvSumReturned: 'returned', rvSumClear: 'unchanged, nothing to look at',
   rvCarriedTitle: 'Carried-over approvals', rvCarriedLead: 'These steps look the same as in the accepted run and their automatic checks passed. Each says who approved it.',
   rvShow: 'Show', rvVerdictLead: 'Carried approvals do not count as accepting the run: a person accepts the run as a whole.',
   rvReturnedHint: 'The author of the run sees returned steps in the inbox, the agent in kaloko feedback.', rvCarriedShort: 'carried over', rvToEnd: 'Summary', rvHint: 'review step by step', rvQueue: 'Steps to review', rvRefFailed: 'The accepted run could not be loaded.', rvComparedWith: 'Compared with the accepted run'
 })
-const RV = { open: false, data: null, idx: 0, view: null, vp: null, refBase: {}, ret: false, busy: false, extra: [] };
+const RV = { open: false, data: null, idx: 0, view: null, vp: null, refBase: {}, ret: false, busy: false, extra: [], flash: null };
 const rvService = () => !!(APP()?.user && APP()?.run && !isDraft());
 const rvWritable = () => rvService() && canWrite();
 const rvItems = () => [...(RV.data?.items || []), ...RV.extra];
@@ -4973,7 +5063,9 @@ function rvFootHtml (it) {
   const items = rvItems();
   const act = it && rvWritable() ? `<button class="btn" id="rvRet">${esc(T('rvReturn'))} <span class="kbd">R</span></button><button class="btn" id="rvCmt">${ICON.comment} ${esc(T('comment'))} <span class="kbd">C</span></button><button class="btn btn--primary" id="rvOk">${esc(T('rvApprove'))} <span class="kbd">A</span></button>`
     : it ? `<span class="note">${esc(T(rvService() ? 'rvReadOnly' : 'rvLocal'))}</span>` : '';
-  return `<div class="rvm__foot"><button class="btn" id="rvPrev" ${RV.idx <= 0 ? 'disabled' : ''}>${ICON.prev} ${esc(T('rvPrev'))} <span class="kbd">K</span></button><span class="spacer"></span>${act}${RV.idx < items.length ? `<button class="btn" id="rvNext">${esc(RV.idx === items.length - 1 ? T('rvToEnd') : T('rvNext'))} ${ICON.next} <span class="kbd">J</span></button>` : ''}</div>`;
+  const f = RV.flash && Date.now() - RV.flash.at < 4000 ? RV.flash : null;
+  const flash = f ? `<p class="rvm__flash rvm__flash--${f.state}" id="rvFlash" role="status">${f.state === 'approved' ? '✓' : '↩'} ${esc(T(f.state === 'approved' ? 'rvApprovedToast' : 'rvReturnedToast'))}: <b>${esc(f.title)}</b>${it ? ` · ${esc(T('rvFlashNext'))} ${esc(loc(byId(it.step)?.title) || it.step)}` : ''}</p>` : '';
+  return `<div class="rvm__foot${it && rvWritable() ? ' rvm__foot--act' : ''}">${flash}<button class="btn" id="rvPrev" ${RV.idx <= 0 ? 'disabled' : ''}>${ICON.prev} ${esc(T('rvPrev'))} <span class="kbd">K</span></button><span class="spacer"></span>${act}${RV.idx < items.length ? `<button class="btn" id="rvNext">${esc(RV.idx === items.length - 1 ? T('rvToEnd') : T('rvNext'))} ${ICON.next} <span class="kbd">J</span></button>` : ''}</div>`;
 }
 function rvEndHtml () {
   const d = RV.data, c = d.counts || {}, items = d.items || [];
@@ -5074,10 +5166,16 @@ async function rvApprove () {
     // the person's look answers what the evaluator could not decide: open criteria pass, then the step is approved
     if (n.kind !== 'stack') for (const c of (n.criteria || []).filter((x) => x.type !== 'deterministic' && rvOpenCrit(x))) await postJson('/criteria', { node_id: n.id, criterion_id: c.id, verdict: 'pass', note: '' });
     await cApi('step', '', 'POST', { node_id: n.id, status: 'approved', note: '' });
-    toast(T('rvApprovedToast'));
+    rvFlash('approved', n);
     await rvAfter(it.step);
   } catch (e) { toast(e.message); if (b) b.disabled = false; } finally { RV.busy = false; }
 }
+/** Feedback after a decision that stays readable on a phone: a line above the buttons (with the next step), a short buzz. */
+function rvFlash (state, n) {
+  RV.flash = { state, title: loc(n?.title) || '', at: Date.now() };
+  try { if (lbPhone()) navigator.vibrate?.(state === 'approved' ? 15 : [15, 60, 15]); } catch {}
+  clearTimeout(RV.flashT); RV.flashT = setTimeout(() => { RV.flash = null; $('rvFlash')?.remove(); }, 4000);
+}
 function rvReturn () { if (!rvCur() || !rvWritable()) return; RV.ret = true; rvRender(); }
 async function rvReturnSend () {
   const it = rvCur(); const t = $('rvRetNote'); if (!it || !t || RV.busy) return;
@@ -5087,7 +5185,7 @@ async function rvReturnSend () {
   try {
     await cApi('step', '', 'POST', { node_id: it.step, status: 'rejected', note, locale: S.loc, viewport: RV.vp || null });
     saveDraft(draftKey('step', it.step, 'return'), '');
-    toast(T('rvReturnedToast'));
+    rvFlash('returned', byId(it.step) || { title: it.title });
     await rvAfter(it.step);
   } catch (e) { toast(e.message); $('rvRetSend') && ($('rvRetSend').disabled = false); } finally { RV.busy = false; }
 }
@@ -5186,7 +5284,7 @@ function applyReviewerVerdicts () {
 }
 async function postJson (path, body) {
   const a = APP();
-  const res = await fetch(`${a.api}/orgs/${a.org}/runs/${a.run}${path}`, { method: 'POST', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
+  const res = await netSend(`${a.api}/orgs/${a.org}/runs/${a.run}${path}`, { method: 'POST', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
   if (res.status === 401) throw sessionLost();
   if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error || `HTTP ${res.status}`);
   return res.json();