kaloko 0.4.9 → 0.4.11

package/src/cli.mjs

@@ -1,9 +1,9 @@
-import { writeFile, access, readFile, mkdir } from 'node:fs/promises'
+import { writeFile, access, readFile, mkdir, rm } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
-import { gzipSync } from 'node:zlib'
-import { createHash } from 'node:crypto'
 import { join, resolve, relative, dirname } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { pathToFileURL, fileURLToPath } from 'node:url'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { availableParallelism } from 'node:os'
 import yaml from 'js-yaml'
 import { loadConfig, environment, urlFor, baseUrl, CONFIG_FILE, LEGACY_CONFIG_FILE } from './lib/config.mjs'
 import { loadScenario, validateScenario } from './lib/scenario.mjs'
@@ -26,6 +26,7 @@ import { doctor, formatDoctor } from './lib/doctor.mjs'
 import { parsePlan, coverage, formatCoverage } from './lib/coverage.mjs'
 import { calibrate, formatCalibration, casesFromGolden, casesFromRun } from './lib/calibrate.mjs'
 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 { DEFAULTS as JEV_DEFAULTS } from './lib/jev.mjs'
@@ -37,6 +38,12 @@ import { service, serviceUrl } from './lib/service.mjs'
 import { login } from './lib/login.mjs'
 import { initNextSteps, loginNextSteps } from './lib/onboarding.mjs'
 import { specCmd, driftCmd } from './lib/spec-cli.mjs'
+import { hashFiles, missingHashes, uploadRunFiles, PROGRESS_FILE, fmtBytes } from './lib/upload.mjs'
+import { affectedFor, carryCaptures } from './lib/affected.mjs'
+import { formatAffected, selectedIds } from './lib/affected-core.mjs'
+import { healStep, formatHeal } from './lib/heal.mjs'
+import { readSource, stepFor, viewportFor, adhocScenario, writeImported, attachImported, keepVideos, slug } from './lib/import.mjs'
+import { findPreview, pullRequestOf, envLines, writeEnvFile, githubWorkflow, gitlabJob, addPreviewEnvironment } from './lib/ci.mjs'
 import { walkDesign, syncDesign, publishVersion, historyCmd, referenceCmd, tokensCmd, exportLive, localRevisions, branchCmd, uploadBlobs } from './lib/design-cli.mjs'
 import { designDir, readBase, headKey } from './lib/design.mjs'
 import { lintDesign, formatLint } from './lib/design-lint.mjs'
@@ -44,8 +51,10 @@ 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'
 import { readTree, flatten } from './lib/apps/tree.mjs'
+import { recordSettings, recordingSession, recordingFiles, traceFiles, stripRecordings, withoutRecordings } from './lib/recording.mjs'
+import { nativeSession } from './lib/apps/recording-native.mjs'
+import { videoCmd } from './lib/video-cli.mjs'
 
-const fmtBytes = (n) => { n = Number(n) || 0; const u = ['B', 'kB', 'MB', 'GB']; let i = 0; while (n >= 1024 && i < u.length - 1) { n /= 1024; i++ } return `${n.toFixed(i ? 1 : 0)} ${u[i]}` }
 
 const HELP = `kaloko — walk, assess and approve what your agents built, on one flow canvas
 
@@ -55,8 +64,18 @@ Project
   draft <url> [url…] [--id SITE-X] [--title t] [--out qa/flows/site.yml] [--force]
                                     First plan + read-only production scenario for public pages, drafted from the
                                     pages (title, description, H1) with the seo, a11y, perf and console packs
-  init [--agent claude|codex|all] [--org <slug>]
-                                    Create ${CONFIG_FILE} and install the kaloko skill for your agent
+  init [--agent claude|codex|all] [--org <slug>] [--no-detect] [--no-scenario]
+                                    Create ${CONFIG_FILE} and install the kaloko skill for your agent; detects the
+                                    framework, dev server URL, locales and main routes, and drafts a first scenario
+                                    (qa/flows/main-pages.yml) when the project has none
+  ci github|gitlab [--scenario a.yml,b.yml] [--env preview] [--trigger deployment|pull_request] [--no-affected]
+       [--out file] [--print] [--force]
+                                    Write a workflow that walks what each pull request affects on its preview
+                                    deployment (Vercel, Netlify, Cloudflare Pages, review apps) and comments on it;
+                                    adds the preview environment (base_url \${KALOKO_PREVIEW_URL}) to the config
+  ci preview-url [--wait 600] [--github-env] [--dotenv file]
+                                    In CI: the preview URL (KALOKO_PREVIEW_URL, the deployment event, provider
+                                    variables or the commit's GitHub deployments), the pull request and its base
   login [--org <slug>] [--url <service>] [--print] [--no-open]
                                     Sign this machine in through the browser: approve the code on kaloko.app, choose
                                     the organization and what the token may do; the token (at most 30 days) goes to
@@ -74,6 +93,7 @@ Run
                                     Create a run directory and make it current
   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]     Download the Chromium of kaloko's Playwright (CI; KALOKO_BROWSER_CHANNEL=chromium uses it)
   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]
@@ -105,6 +125,27 @@ Run
                                     path contains a, b; at most N pages (default items.limit, 500)
        [--stability N]              Take N screenshots of each capture a moment apart and note regions that move
                                     (clocks, carousels); kaloko stability turns them into ignore suggestions
+       [--concurrency N]            Locales at the same time, each in its own browser context (default: by CPU in an
+                                    own browser, 1 on the shared browser; walk.concurrency in the config)
+       [--affected [--base ref] [--no-upstream] [--if-unmapped all] [--carry]]
+                                    Only the steps the changed files reach (see kaloko affected), plus steps on the
+                                    main path before them and steps with affects: always; --carry copies the other
+                                    steps' captures from the previous local run
+       [--heal | --no-heal]         A selector the page lost gets a proposal from the page (test id, role and name,
+                                    text) with a patch; --heal applies it to the step script once the step passes
+       [--record [step|flow|failed]] [--record-quality low|medium|high] [--no-trace]
+                                    Record each step from the previous screen to its capture (step), the whole walk
+                                    per locale with a chapter per step (flow), or only steps that fail (failed);
+                                    also capture.record in the config or scenario, record: true on a step.
+                                    A trace (actions, requests, console) is kept per step unless --no-trace
+  affected [--scenario file | --all] [--base ref] [--files a,b] [--json] [--check] [--offline]
+                                    Which steps changed files reach, and why: framework route files against step paths
+                                    and URLs captured earlier, imports, global files, i18n messages, step scripts and
+                                    affects: globs; --check exits 1 when nothing is affected
+  import <folder | playwright-report/ | results.json | trace.zip | walkthrough.md> [--scenario file | --adhoc]
+         [--env e] [--locale l] [--viewport v] [--map "Title=step,…"] [--format f] [--out file]
+                                    Screenshots, recordings and traces from agents and tools as a run: into the
+                                    current run, a new run of --scenario, or an ad-hoc flow of the screens
   status                            Show what the current run has captured
                                     Scenarios may declare "sessions" (people in the flow); walk keeps one browser context per session and locale
 
@@ -114,9 +155,16 @@ Results
                                     the semantic questions again on the stored captures (no walk);
                                     console, overflow and performance keep their live result
   build                             Write run.json and the local preview (index.html)
+  video export [--format mp4|webm|gif] [--locale l] [--steps a,b] [--lang en|cs] [--out file]
+                                    The run's recordings in flow order with a title card per step (title, verdict);
+                                    shared with the run on Business and up
+  video list | trace --step <id> | tools
+                                    Recordings and traces of the run; a step's trace as a timeline; ffmpeg, adb, simctl
   preview                           Build and print the preview path
-  share [--expires 30] [--pr]       Upload the run to kaloko.app (KALOKO_TOKEN, tester role);
-                                    --pr adds or updates one comment on the branch's pull request via gh
+  share [--expires 30] [--pr]       Upload the run to kaloko.app (KALOKO_TOKEN, tester role); files travel by content
+                                    hash, so unchanged captures are not sent again and a broken-off share resumes;
+                                    --pr adds or updates one comment on the branch's pull request via gh (KALOKO_PR in
+                                    CI), or a note on the GitLab merge request (KALOKO_GITLAB_TOKEN)
   feedback [--run id] [--scenario id] [--json]
                                     Open threads from reviewers (steps, the whole run, the whole flow) with ids and replies;
                                     returned steps first, with their notes
@@ -237,7 +285,40 @@ function parse (argv) {
   return args
 }
 const list = (v) => (typeof v === 'string' ? v.split(',').map((s) => s.trim()).filter(Boolean) : null)
-const say = (...m) => console.log(...m)
+// parallel walks (#27) print each locale's lines together, in locale order: `say` writes into the running unit's buffer
+const output = new AsyncLocalStorage()
+const say = (...m) => { const buf = output.getStore(); if (buf) buf.push(m.join(' ')); else console.log(...m) }
+
+/**
+ * Runs `job` over `items`, `n` at a time, and returns the results in item order. The first item prints live; the
+ * others print in item order once every earlier one is done, so the log reads the same however the work interleaved.
+ */
+export async function inOrder (items, n, job, print = (l) => console.log(l)) {
+  const results = new Array(items.length)
+  if (n <= 1) { for (const [i, it] of items.entries()) results[i] = await job(it); return results }
+  const bufs = items.map(() => []); const finished = items.map(() => false)
+  let printed = 1
+  const flush = () => { while (printed < items.length && finished[printed - 1] && finished[printed]) { for (const l of bufs[printed]) print(l); printed++ } }
+  const queue = items.map((_, i) => i)
+  const worker = async () => {
+    for (let i = queue.shift(); i !== undefined; i = queue.shift()) {
+      results[i] = await (i === 0 ? job(items[i]) : output.run(bufs[i], () => job(items[i])))
+      finished[i] = true
+      flush()
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker))
+  flush()
+  return results
+}
+
+/** Locales walked at once: --concurrency, walk.concurrency, else by CPU (one at a time on the shared browser). */
+export function walkConcurrency (args, config, units, shared, cpus = availableParallelism()) {
+  const asked = Number(args.concurrency) || Number(config.walk?.concurrency)
+  if (asked) return Math.max(1, Math.min(16, Math.floor(asked)))
+  if (units < 2 || shared) return 1
+  return Math.max(1, Math.min(units, 4, Math.floor(cpus / 2)))
+}
 
 async function context (args) {
   const { config, root, file } = await loadConfig(process.cwd(), args.config)
@@ -437,6 +518,14 @@ function linkFor (env, node, locale) {
   if (/^[a-z][a-z0-9+.-]*:/i.test(p)) return p
   return env.base_url ? urlFor(env, { path: p }, locale) : null
 }
+/** A headless Chrome of its own for encoding recordings, started on first use (one per walk). */
+function lazyEncoder (config) {
+  let started = null
+  return {
+    page: () => (started ||= launchEphemeral(config).then(async (b) => ({ b, p: await b.newPage() })).catch(() => ({ b: null, p: null }))).then((x) => x.p),
+    close: async () => { if (started) await (await started).b?.close().catch(() => {}) }
+  }
+}
 const appViewport = (run) => Object.keys(run.meta.scope.viewports || {})[0] || null
 
 /**
@@ -454,6 +543,8 @@ async function walkApp ({ config, root, run, scenario, env, args }) {
   const encoder = enc ? await enc.newPage().catch(() => null) : null
   const streak = failureStreak(args['keep-going'] ? 0 : 3)
   const maxChars = config.evaluators?.jev?.max_state_chars
+  // recordings and traces (batch D): Electron windows use the screencast recorder, devices record themselves
+  const recSettings = recordSettings({ args, config, scenario })
   try {
     for (const locale of locales) {
       const driver = driverFor(platform, env, { root, scenarioDir, locale })
@@ -462,6 +553,9 @@ async function walkApp ({ config, root, run, scenario, env, args }) {
         if (driver.web) observeConsole(driver.page)
         say(`${platform} ${locale}: ${driver.web ? 'Electron window' : 'app'} ready`)
       } catch (error) { failed.push(`${platform} (${locale}): ${error.message.split('\n')[0]}`); say(`✗ ${platform} ${locale}: ${error.message.split('\n')[0]}`); await driver.close().catch(() => {}); if (error instanceof UserError) break; continue }
+      const rec = driver.web
+        ? await recordingSession({ page: driver.page, run, scenario, locale, settings: recSettings, viewports: run.meta.scope.viewports, encoder: async () => encoder, say, label: `${platform} ${locale}` }).catch(() => null)
+        : await nativeSession({ platform, env, run, scenario, locale, settings: recSettings, driver, encoder: async () => encoder, say }).catch(() => null)
       try {
         for (const node of scenario.nodes) {
           if (node.kind === 'decision' || (pick && !pick.includes(node.id))) continue
@@ -474,30 +568,42 @@ async function walkApp ({ config, root, run, scenario, env, args }) {
           const link = linkFor(env, node, locale)
           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 }
           if (streak.stopped(locale)) { skipped.push(`${node.id} (${locale})`); continue }
+          const records = []
           try {
             let captured = false
+            await rec?.beforeStep(node)
             const capture = async (o = {}) => {
               captured = true
+              await rec?.beforeCapture(node)
               if (driver.web) {
                 const [w, h] = await driver.page.evaluate(() => [innerWidth, innerHeight])
-                return captureStep({ page: driver.page, node, locale, options: captureOptions(scenario, node), viewports: { [o.viewport || appViewport(run) || 'window']: [w, h] }, run, consoleFile: null, maxChars, extra: { platform, device: 'Electron' } })
+                const r = await captureStep({ page: driver.page, node, locale, options: captureOptions(scenario, node), viewports: { [o.viewport || appViewport(run) || 'window']: [w, h] }, run, consoleFile: null, maxChars, extra: { platform, device: 'Electron' } })
+                records.push(...r)
+                return r
               }
-              return captureApp({ snapshot: await driver.snapshot(), node, locale, viewport: o.viewport || appViewport(run), run, platform, encoder, maxChars, extra: { url: link } })
+              const r = await captureApp({ snapshot: await driver.snapshot(), node, locale, viewport: o.viewport || appViewport(run), run, platform, encoder, maxChars, extra: { url: link } })
+              records.push(r)
+              return r
             }
             if (scripted) {
               const mod = await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href)
               await mod.default({ app: driver, page: driver.page || null, locale, node: { id: node.id, title: localized(node.title, locale), kind: node.kind }, 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 rec?.afterStep(node, driver.web ? { records } : { record: records[0] })
             say(`✓ ${node.id} ${locale}`)
             streak.ok(locale)
           } catch (error) {
+            await rec?.afterStep(node, driver.web ? { error, records } : { error, record: records[0] }).catch(() => {})
             failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
             say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
             if (streak.record(locale, error.message)) say(`  stopping ${locale}: the last 3 steps failed with the same error`)
           }
         }
-      } finally { await driver.close().catch(() => {}) }
+      } finally {
+        for (const n of (await rec?.finish().catch((e) => [`recording: ${e.message}`])) || []) say(`  ${n}`)
+        await driver.close().catch(() => {})
+      }
     }
   } finally { await enc?.close().catch(() => {}) }
   if (pending.length) say(`\nSteps for an agent or a person (drive the app, then kaloko capture --step <id> --image shot.png [--tree dump.xml|json]):\n  - ${[...new Set(pending)].join('\n  - ')}`)
@@ -536,6 +642,13 @@ async function captureImage ({ config, run, scenario, node, locale, args }) {
   } finally { await enc?.close().catch(() => {}) }
 }
 
+/** walk --affected / kaloko affected: the selection for one scenario (a token adds URLs of the newest shared run). */
+async function affectedSelection (args, { config, root, scenario, scenarioFile }) {
+  let client = null
+  try { if (!args.offline) client = service(config) } catch {}
+  return affectedFor({ root, config, scenario, scenarioFile, base: typeof args.base === 'string' ? args.base : null, files: list(args.files), client, upstream: !args['no-upstream'] })
+}
+
 const commands = {
   async init (args) {
     const cwd = process.cwd()
@@ -544,14 +657,22 @@ const commands = {
     try { await access(file); exists = true } catch {}
     // a project from before the rename keeps its qawalk.config.yml (it is still read)
     try { await access(join(cwd, LEGACY_CONFIG_FILE)); exists = true; say(`${LEGACY_CONFIG_FILE} found; kept (still read; rename it to ${CONFIG_FILE} when convenient).`) } catch {}
+    // what the project is (#26): framework, dev server, locales, main routes; --no-detect keeps the plain template
+    const detected = args['no-detect'] ? null : await detectProject(cwd)
+    if (detected) say(formatDetection(detected))
     if (!exists) {
       let tpl = await readFile(join(packageRoot, 'templates', 'kaloko.config.yml'), 'utf8')
       if (typeof args.org === 'string') {
         if (!/^[a-z0-9][a-z0-9-]{1,40}$/.test(args.org)) throw new UserError('--org must be the organization slug from kaloko.app (a-z, 0-9, -).')
         tpl = tpl.replace(/^org: .*$/m, `org: ${args.org}`)
       }
+      if (detected) {
+        const project = (detected.name || cwd.split('/').pop() || '').toLowerCase().replace(/^@[^/]+\//, '').replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '')
+        if (project) tpl = tpl.replace(/^project: .*$/m, `project: ${project}`)
+        tpl = tpl.replace('  local:\n    base_url:\n      default: http://localhost:3000', `  local:\n    # dev server: ${detected.command || 'start your app'}${detected.framework ? ` (${detected.framework.name}, found by kaloko init)` : ''}\n    base_url:\n      default: ${detected.url}`)
+      }
       await writeFile(file, tpl)
-      say(`Created ${CONFIG_FILE}. Edit org and environments.`)
+      say(`Created ${CONFIG_FILE}${detected ? ` (local: ${detected.url})` : ''}. Edit org and the staging and production environments.`)
     } else if (!existsSync(join(cwd, LEGACY_CONFIG_FILE))) say(`${CONFIG_FILE} already exists; kept.`)
     const agent = typeof args.agent === 'string' ? args.agent : 'none'
     if (!['claude', 'codex', 'all', 'none'].includes(agent)) throw new UserError('--agent must be claude, codex, all or none.')
@@ -584,12 +705,32 @@ const commands = {
       await cp(join(packageRoot, 'templates', 'steps', 'consent.mjs'), consentStep)
       say('Added qa/flows/steps/consent.mjs (accepts the consent dialog, if the site has one)')
     }
+    // a first scenario that walks as it is, when the project has none yet
+    let first = null
+    if (detected && !args['no-scenario']) {
+      try {
+        const { config, root } = await loadConfig(cwd)
+        if (!(await scenarioFiles(config, root)).length) {
+          const scenario = initScenario(detected)
+          const problems = validateScenario(JSON.parse(JSON.stringify(scenario)))
+          if (problems.length) throw new Error(problems.join('; '))
+          first = join(cwd, 'qa', 'flows', 'main-pages.yml')
+          await mkdir(join(cwd, 'qa', 'flows', 'steps'), { recursive: true })
+          await writeFile(first, `# First scenario drafted by kaloko init from ${detected.routes.length ? 'the route files' : 'the home page'}; sharpen purposes and criteria, add the flows that matter.\n${scenarioYaml(scenario)}`)
+          const open = join(cwd, 'qa', 'flows', 'steps', 'open.mjs')
+          if (!existsSync(open)) await writeFile(open, "// Opens the step's page (kaloko init).\nexport default async ({ page, url }) => { await page.goto(url(), { waitUntil: 'domcontentloaded' }) }\n")
+          say(`Drafted ${relative(cwd, first)}: ${scenario.nodes.length} page(s) in ${scenario.locales.join(', ')}`)
+        }
+      } catch (e) { say(`No scenario drafted: ${e.message.split('\n')[0]}`) }
+    }
+    let running = false
+    if (detected) { try { const r = await fetch(detected.url, { signal: AbortSignal.timeout(1500) }); running = r.status < 500 } catch {} }
     // the organization's sample run and the way to a first real flow (src/lib/onboarding.mjs)
     let written = ''
     try { written = await readFile(existsSync(file) ? file : join(cwd, LEGACY_CONFIG_FILE), 'utf8') } catch {}
     const org = typeof args.org === 'string' ? args.org : (written.match(/^org:\s*["']?([a-z0-9-]+)["']?\s*$/m) || [])[1]
     const base = serviceUrl({ share: { url: (written.match(/^share:[ \t]*\n(?:[ \t]+.*\n)*?[ \t]+url:[ \t]*["']?(https?:\/\/[^\s"']+)/m) || [])[1] } })
-    say(initNextSteps({ base, org }).join('\n'))
+    say(initNextSteps({ base, org, loggedIn: !!process.env.KALOKO_TOKEN, devServer: detected && !running ? detected : null, scenario: first && relative(cwd, first) }).join('\n'))
     say(`Scenario template: ${join(packageRoot, 'templates', 'scenario.yml')}`)
   },
 
@@ -647,6 +788,14 @@ const commands = {
   async browser (args) {
     const { config, root } = await context(args)
     const action = args._[0] || 'status'
+    if (action === 'install') {
+      // the Chromium of the Playwright version kaloko itself uses (CI: --with-deps adds the system libraries)
+      const { spawn } = await import('node:child_process')
+      const cli = join(dirname(fileURLToPath(import.meta.resolve('playwright/package.json'))), 'cli.js')
+      const code = await new Promise((done) => spawn(process.execPath, [cli, 'install', ...(args['with-deps'] ? ['--with-deps'] : []), 'chromium'], { stdio: 'inherit' }).on('close', done))
+      if (code) throw new UserError(`Installing Chromium failed (exit ${code}).`)
+      return
+    }
     let env = null
     if (typeof args.env === 'string') env = environment(config, args.env)
     else { try { const run = await resolveRun({ root, output: config.output, run: args.run }); env = environment(config, run.meta.environment.name) } catch {} }
@@ -750,8 +899,31 @@ const commands = {
     say(`✓ ${node.id} ${locale}: "${results.subject}" → ${results.count} viewport(s)`)
   },
 
+  async video (args) {
+    const { config, root } = await context(args)
+    await videoCmd({ config, root, args, say })
+  },
+
   async walk (args) {
     const { config, root, run, scenario, env } = await runContext(args)
+    if (args.affected) {
+      // only the steps the changes reach (#14), explained; the rest stays as it was (or is carried with --carry)
+      const r = await affectedSelection(args, { config, root, scenario, scenarioFile: resolve(root, run.meta.scenario_file) })
+      say(formatAffected(r.sel, { scenario, base: r.base, changed: r.files.length }))
+      if (args['if-unmapped'] === 'all' && r.sel.unmapped.length) say('Unmapped changes: walking every step (--if-unmapped all).\n')
+      else {
+        let ids = selectedIds(scenario, r.sel)
+        if (list(args.steps)) ids = ids.filter((id) => list(args.steps).includes(id))
+        if (!ids.length || r.sel.none) { say('Nothing to walk: no change reaches a step of this scenario.'); return }
+        args.steps = ids.join(',')
+        if (r.sel.locales && !args.locales) { const ls = r.sel.locales.filter((l) => run.meta.scope.locales.includes(l)); if (ls.length) args.locales = ls.join(',') }
+        if (args.carry) {
+          const c = await carryCaptures({ root, output: config.output, run, scenario, walked: new Set(ids) })
+          say(c ? `Carried ${c.steps.length} step(s) not walked from run ${c.from}: ${c.steps.join(', ')}` : 'Nothing to carry: no earlier local run of this scenario on this environment.')
+        }
+        say('')
+      }
+    }
     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 })
@@ -766,17 +938,23 @@ const commands = {
     const conn = args.ephemeral ? null : await connectBrowser({ root, config, env })
     const releaseLock = conn ? await acquireWalkLock({ root, config, env, run: run.meta.id }).catch(async (e) => { await conn.browser.close(); throw e }) : null
     const ephemeral = conn ? null : await launchEphemeral(config)
-    const ctx = conn ? conn.context : await newContext(ephemeral, env, { root, config })
+    const browser = conn ? conn.browser : ephemeral
+    // locales are independent: with --concurrency > 1 each walks in its own browser context at the same time (#27);
+    // one locale at a time keeps the shared browser's own context, as before
+    const concurrency = walkConcurrency(args, config, locales.length, !!conn)
+    const parallel = concurrency > 1 && locales.length > 1
+    const ctx = parallel ? null : conn ? conn.context : await newContext(ephemeral, env, { root, config })
     const scenarioDir = resolve(root, run.meta.scenario_file, '..')
     // semantic questions of every new capture start right away; the walk ends with the verdicts (--no-evaluate: skip)
     const prefetch = args['no-evaluate'] ? null : semanticPrefetch({ scenario, config, root })
-    const pending = []
-    const failed = []
-    const skipped = []
     const walked = await readCaptures(run.dir)
+    // recordings and traces (batch D, #12): opt-in recordings, traces unless turned off; encoded in an own headless Chrome
+    const recSettings = recordSettings({ args, config, scenario })
+    const encoder = lazyEncoder(config)
     const sessions = scenario.sessions || null
     // named sessions: one isolated browser context per person and locale (cookies, storage, sign-in), created lazily
     const sessionContexts = new Map()
+    const ownContexts = []
     // `account` stays the scenario's key; `credentials` resolves it in this environment (config accounts)
     const sessionInfo = (key) => key && sessions?.[key] ? { key, title: localized(sessions[key].title, locales[0]), mailbox: sessions[key].mailbox ? expandRun(sessions[key].mailbox, run.meta.short) : null, account: sessions[key].account || null, credentials: accountFor(env, sessions[key].account, { root, config }) } : null
     const contextFor = async (key, locale) => {
@@ -785,7 +963,7 @@ const commands = {
       if (!sessionContexts.has(id)) {
         // every context gets the environment's gate and readonly policy; an account's saved sign-in is loaded
         const account = accountFor(env, sessions[key].account, { root, config })
-        const c = await newContext(conn ? conn.browser : ephemeral, env, { root, config, account })
+        const c = await newContext(browser, env, { root, config, account })
         const p = await c.newPage()
         observeConsole(p)
         sessionContexts.set(id, { context: c, page: p })
@@ -797,76 +975,265 @@ const commands = {
     // stop a session after the same failure repeats (shared precondition such as a failed sign-in);
     // --keep-going walks every step regardless
     const streak = failureStreak(args['keep-going'] ? 0 : 3)
-    try {
-      for (const locale of locales) {
-        // the walk owns its tab; agents and people keep theirs in the same shared browser
-        const page = await ctx.newPage()
-        if (!conn) observeConsole(page)
-        try {
-          // every locale starts as a new visitor on its first walk in the run
-          if (conn && !walked.some((c) => c.locale === locale)) { await resetSession(ctx, page, baseUrl(env, locale)); say(`session reset (new visitor, ${locale})`) }
-          for (const node of scenario.nodes) {
-            if (node.kind === 'decision' || (pick && !pick.includes(node.id))) continue
-            if (node.kind !== 'stack' && node.path && !urlFor(env, node, locale)) continue // step does not exist in this locale
-            if (node.session && sessions?.[node.session]?.blocked_on?.includes(env.name)) { pending.push(`${node.id} (${locale}): session ${node.session} is blocked on ${env.name}`); continue }
-            const sess = await contextFor(node.session, locale)
-            const sPage = sess ? sess.page : page
-            const sCtx = sess ? sess.context : ctx
-            if (node.kind === 'stack') {
-              try {
-                const bad = await walkStack({ node, locale, page: sPage, env, run, scenario, scenarioDir, config, consoleFile: conn && !sess ? consoleLog(root, config.output, env.name) : null, args })
-                for (const b of bad) failed.push(`${node.id} (${locale}) ${b}`)
-              } catch (error) {
-                failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
-                say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
-              }
-              continue
+    const proposals = []
+    // one locale: its own tab (and, in parallel, its own context); returns what it could not walk
+    const walkLocale = async (locale) => {
+      const pending = []; const failed = []; const skipped = []
+      let lctx = ctx
+      if (parallel) { lctx = await newContext(browser, env, { root, config }); ownContexts.push(lctx) }
+      // the walk owns its tab; agents and people keep theirs in the same shared browser
+      const page = await lctx.newPage()
+      const shared = conn && !parallel // the shared browser's own context logs its console to a file
+      if (!shared) observeConsole(page)
+      // one recorder per page (the walk's tab and each named session's), started on its first step
+      const recorders = new Map()
+      const recorderFor = async (p) => {
+        if (!recorders.has(p)) recorders.set(p, recordingSession({ page: p, run, scenario, locale, settings: recSettings, viewports: run.meta.scope.viewports, encoder: encoder.page, say, label: locale }).catch(() => null))
+        return recorders.get(p)
+      }
+      try {
+        // every locale starts as a new visitor on its first walk in the run (an own context is new already)
+        if (shared && !walked.some((c) => c.locale === locale)) { await resetSession(lctx, page, baseUrl(env, locale)); say(`session reset (new visitor, ${locale})`) }
+        for (const node of scenario.nodes) {
+          if (node.kind === 'decision' || (pick && !pick.includes(node.id))) continue
+          if (node.kind !== 'stack' && node.path && !urlFor(env, node, locale)) continue // step does not exist in this locale
+          if (node.session && sessions?.[node.session]?.blocked_on?.includes(env.name)) { pending.push(`${node.id} (${locale}): session ${node.session} is blocked on ${env.name}`); continue }
+          const sess = await contextFor(node.session, locale)
+          const sPage = sess ? sess.page : page
+          const sCtx = sess ? sess.context : lctx
+          const consoleFile = shared && !sess ? consoleLog(root, config.output, env.name) : null
+          if (node.kind === 'stack') {
+            try {
+              const bad = await walkStack({ node, locale, page: sPage, env, run, scenario, scenarioDir, config, consoleFile, args })
+              for (const b of bad) failed.push(`${node.id} (${locale}) ${b}`)
+            } catch (error) {
+              failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
+              say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
             }
-            if (node.kind === 'email' && (node.mail?.to || sessionInfo(node.session)?.mailbox)) {
-              // an e-mail node with a recipient is walked like a step: wait for the message and capture it
-              try {
-                const to = expandRun(node.mail?.to || sessionInfo(node.session).mailbox, run.meta.short)
-                const results = await captureMail({ config, root, run, env, node, locale, to, subject: localized(node.mail?.subject, locale), timeoutMs: 45000 })
-                say(`✓ ${node.id} ${locale}: "${results.subject}"`)
-              } catch (error) {
-                failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
-                say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
-              }
-              continue
+            continue
+          }
+          if (node.kind === 'email' && (node.mail?.to || sessionInfo(node.session)?.mailbox)) {
+            // an e-mail node with a recipient is walked like a step: wait for the message and capture it
+            try {
+              const to = expandRun(node.mail?.to || sessionInfo(node.session).mailbox, run.meta.short)
+              const results = await captureMail({ config, root, run, env, node, locale, to, subject: localized(node.mail?.subject, locale), timeoutMs: 45000 })
+              say(`✓ ${node.id} ${locale}: "${results.subject}"`)
+            } catch (error) {
+              failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
+              say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
             }
-            if (!['playwright', 'script'].includes(node.execution.strategy) || !node.execution.script) { pending.push(`${node.id} (${locale}): ${node.execution.strategy} — ${node.execution.instructions.split('\n')[0]}`); continue }
-            const streakKey = `${node.session || ''}|${locale}`
-            if (streak.stopped(streakKey)) { skipped.push(`${node.id} (${locale})`); continue }
+            continue
+          }
+          if (!['playwright', 'script'].includes(node.execution.strategy) || !node.execution.script) { pending.push(`${node.id} (${locale}): ${node.execution.strategy} — ${node.execution.instructions.split('\n')[0]}`); continue }
+          const streakKey = `${node.session || ''}|${locale}`
+          if (streak.stopped(streakKey)) { skipped.push(`${node.id} (${locale})`); continue }
+          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) => {
+            let captured = false
+            rec?.beforeStep(node)
+            const records = []
+            const capture = (opts = {}) => { captured = true; rec?.beforeCapture(node); return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeViewports(run, opts.viewports), 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 {
-              const mod = await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href)
-              // the automatic capture runs unless this script invocation 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)
-              let captured = false
-              const capture = (opts = {}) => { captured = true; return captureStep({ page: sPage, node, locale, options: captureOptions(scenario, node), viewports: scopeViewports(run, opts.viewports), run, htmlView: htmlViewAllowed(env, scenario) ? { scenarioId: scenario.id } : null, consoleFile: conn && !sess ? consoleLog(root, config.output, env.name) : null, 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); return r }) }
               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) })
               if (!captured) await capture()
-              say(`✓ ${node.id} ${locale}`)
+            } catch (error) { await rec?.afterStep(node, { error }); throw error }
+            await rec?.afterStep(node, { records })
+          }
+          try {
+            await runStep(await import(pathToFileURL(scriptFile).href))
+            say(`✓ ${node.id} ${locale}`)
+            streak.ok(streakKey)
+          } 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)
+            if (healed?.applied) {
+              say(`✓ ${node.id} ${locale} (healed)\n${formatHeal(healed, { stepArg: node.id })}`)
               streak.ok(streakKey)
-            } catch (error) {
-              failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
-              say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
-              if (streak.record(streakKey, error.message)) say(`  stopping ${node.session ? `session ${node.session}` : 'this walk'} (${locale}): the last 3 steps failed with the same error; fix the shared cause (sign-in, environment) and rerun, or pass --keep-going`)
+              continue
             }
+            failed.push(`${node.id} (${locale}): ${error.message.split('\n')[0]}`)
+            say(`✗ ${node.id} ${locale}: ${error.message.split('\n')[0]}`)
+            if (healed) { say(formatHeal(healed, { stepArg: node.id })); if (healed.patch) proposals.push(node.id) }
+            if (streak.record(streakKey, error.message)) say(`  stopping ${node.session ? `session ${node.session}` : 'this walk'} (${locale}): the last 3 steps failed with the same error; fix the shared cause (sign-in, environment) and rerun, or pass --keep-going`)
           }
-        } finally { await page.close().catch(() => {}) }
+        }
+      } finally {
+        for (const r of recorders.values()) { const notes = await (await r)?.finish().catch((e) => [`recording: ${e.message}`]); for (const n of notes || []) say(`  ${n}`) }
+        await page.close().catch(() => {})
       }
+      return { pending, failed, skipped }
+    }
+    let results
+    try {
+      if (parallel) say(`Walking ${locales.length} locales, ${concurrency} at a time (each in its own browser context); output in locale order.`)
+      results = await inOrder(locales, parallel ? concurrency : 1, (locale) => walkLocale(locale).catch((error) => ({ pending: [], failed: [`${locale}: ${error.message.split('\n')[0]}`], skipped: [] })))
     } finally {
       for (const { context } of sessionContexts.values()) await context.close().catch(() => {})
+      for (const c of ownContexts) await c.close().catch(() => {})
       if (conn) await conn.browser.close() // over CDP this only disconnects; the shared browser keeps running
       if (ephemeral) await ephemeral.close()
+      await encoder.close()
       await releaseLock?.()
     }
+    const pending = results.flatMap((r) => r.pending); const failed = results.flatMap((r) => r.failed); const skipped = results.flatMap((r) => r.skipped)
     if (pending.length) say(`\nSteps for an agent or a person (capture them with kaloko capture --step <id>):\n  - ${[...new Set(pending)].join('\n  - ')}`)
     if (failed.length) { say(`\nSteps that failed (fix and rerun with --steps):\n  - ${failed.join('\n  - ')}`); process.exitCode = 1 }
+    if (proposals.length) say(`\nSelector proposals above: review the patch, then kaloko walk --steps ${[...new Set(proposals)].join(',')} --heal applies it once the step passes.`)
     if (skipped.length) { say(`\nSteps not walked after repeated failures (rerun with --steps once the cause is fixed):\n  - ${skipped.join('\n  - ')}`); process.exitCode = 1 }
     if (prefetch) await walkVerdicts({ prefetch, run, scenario, config, root })
   },
 
+  async affected (args) {
+    const { config, root } = await context(args)
+    let targets = []
+    if (typeof args.scenario === 'string') targets = [resolve(args.scenario)]
+    else {
+      try { const r = await resolveRun({ root, output: config.output, run: args.run }); targets = [resolve(root, r.meta.scenario_file)] } catch {}
+      if (!targets.length || args.all) targets = await scenarioFiles(config, root)
+    }
+    if (!targets.length) throw new UserError('No scenario: pass --scenario <file>, start a run, or list scenarios in the config.')
+    const out = []
+    for (const file of targets) {
+      const scenario = await loadScenario(file)
+      const r = await affectedSelection(args, { config, root, scenario, scenarioFile: file })
+      out.push({ scenario: scenario.id, file: relative(root, file), base: r.base, changed: r.files, runs: r.runs, ...r.sel, walk: selectedIds(scenario, r.sel) })
+      if (!args.json) say(formatAffected(r.sel, { scenario, base: r.base, changed: r.files.length }) + '\n')
+    }
+    if (args.json) say(JSON.stringify(targets.length === 1 && typeof args.scenario === 'string' ? out[0] : out, null, 2))
+    else if (!args.check) say(`Walk them with: kaloko walk --affected${args.base ? ` --base ${args.base}` : ''} (after kaloko start)`)
+    // --check: exit code 1 when nothing is affected (CI skips the scenario)
+    if (args.check && !out.some((o) => o.walk.length && !o.none)) process.exitCode = 1
+  },
+
+  /**
+   * `kaloko import <path>` (#11): screenshots, recordings and traces from agents and tools as a run: into the current
+   * run, a new run of --scenario, or an ad-hoc flow made from the screens themselves.
+   */
+  async import (args) {
+    const from = args._[0]
+    if (!from) throw new UserError('Usage: kaloko import <folder | playwright-report/ | results.json | trace.zip | walkthrough.md> [--scenario file | --adhoc] [--env e] [--locale l] [--viewport v] [--map "Title=step,…"]')
+    const { config, root } = await context(args)
+    let source
+    try { source = await readSource(resolve(from), typeof args.format === 'string' ? args.format : 'auto') } catch (e) { throw new UserError(`kaloko import: ${e.message}`) }
+    if (!source.items.length) throw new UserError(`No screenshots found in ${from} (${source.format}). A folder needs .png, .jpg or .webp files, a steps.json or a Markdown walkthrough with images; a Playwright report needs screenshot attachments or a trace.`)
+    say(`Read ${source.items.length} screen(s)${source.videos.length ? ` and ${source.videos.length} recording(s)` : ''} from ${from} (${source.format}${source.tool !== source.format ? `, ${source.tool}` : ''})`)
+    const envName = () => {
+      if (typeof args.env === 'string') return args.env
+      const names = Object.keys(config.environments).filter((n) => config.environments[n].kind !== 'design')
+      for (const n of ['local', ...names]) { try { if (config.environments[n]) { environment(config, n); return n } } catch {} }
+      throw new UserError('Pass --env <name>: no environment of the config resolves here.')
+    }
+    let run = null
+    let scenarioFile = null
+    if (typeof args.scenario === 'string') scenarioFile = resolve(args.scenario)
+    else if (!args.adhoc) { try { run = await resolveRun({ root, output: config.output, run: args.run }) } catch {} }
+    if (!run && !scenarioFile) {
+      // an ad-hoc flow: one manual screen per imported item, in order; read-only, it never touched the environment
+      const scenario = adhocScenario(source, { id: typeof args.id === 'string' ? args.id : undefined, title: typeof args.title === 'string' ? args.title : undefined, locale: typeof args.locale === 'string' ? args.locale : 'en' })
+      scenario.readonly = true
+      const problems = validateScenario(JSON.parse(JSON.stringify(scenario)))
+      if (problems.length) throw new UserError(`The ad-hoc flow did not validate:\n  - ${problems.join('\n  - ')}`)
+      scenarioFile = resolve(root, typeof args.out === 'string' ? args.out : join('qa', 'flows', `${slug(scenario.id)}.yml`))
+      if (existsSync(scenarioFile) && !args.force) throw new UserError(`${relative(process.cwd(), scenarioFile)} exists; pass --out <file> or --force.`)
+      await mkdir(dirname(scenarioFile), { recursive: true })
+      await writeFile(scenarioFile, `# Ad-hoc flow from kaloko import ${from}: rename steps, add purposes and criteria, or map the screens onto a real scenario.\n${scenarioYaml(scenario)}`)
+      say(`Wrote the ad-hoc flow ${relative(process.cwd(), scenarioFile)} (${scenario.nodes.length} steps)`)
+    }
+    if (!run) {
+      await commands.start({ scenario: scenarioFile, env: envName(), locales: args.locales, viewports: args.viewports, executor: args.executor || `import:${source.tool}`, config: args.config, _: [] })
+      run = await resolveRun({ root, output: config.output })
+    } else say(`Importing into run ${run.meta.id} (${run.meta.scenario.id}); --adhoc or --scenario starts a new one`)
+    const scenario = await loadScenario(resolve(root, run.meta.scenario_file))
+    const map = Object.fromEntries((list(args.map) || []).map((p) => p.split('=')).filter((p) => p.length === 2 && p[0] && p[1]).map(([a, b]) => [a.trim(), b.trim()]))
+    const locale = typeof args.locale === 'string' && run.meta.scope.locales.includes(args.locale) ? args.locale : run.meta.scope.locales[0]
+    const enc = await launchEphemeral(config).catch(() => null)
+    const encoder = enc ? await enc.newPage().catch(() => null) : null
+    const used = new Set(); const unmatched = []; let captured = 0; let attached = 0
+    try {
+      for (const item of source.items) {
+        const hit = stepFor(item, scenario.nodes, map)
+        if (!hit) { unmatched.push(item.title); say(`? ${item.title}: no step matches`); continue }
+        const loc = item.locale && run.meta.scope.locales.includes(item.locale) ? item.locale : locale
+        const vp = viewportFor(item.size, run.meta.scope.viewports, item.viewport || (typeof args.viewport === 'string' ? args.viewport : null))
+        const key = `${hit.node.id}|${loc}|${vp}`
+        if (used.has(key)) { await attachImported({ run, node: hit.node, locale: loc, item }); attached++; say(`+ ${item.title} → attached to ${hit.node.id}`); continue }
+        used.add(key)
+        await writeImported({ run, node: hit.node, locale: loc, viewport: vp, item, tool: source.tool, encoder })
+        captured++
+        say(`✓ ${item.title} → ${hit.node.id} ${loc}/${vp} (${hit.how})`)
+      }
+    } finally { await enc?.close().catch(() => {}) }
+    const kept = await keepVideos(run, source.videos)
+    say(`\nImported ${captured} screen(s)${attached ? `, ${attached} more as attachments` : ''} into ${run.meta.id}.${encoder ? '' : ' (No Chrome: images kept as they are, without thumbnails.)'}`)
+    if (unmatched.length) say(`Not matched to a step (${unmatched.length}): name the step in steps.json ("step": "<id>"), or pass --map "${unmatched[0]}=<step id>". Steps: ${scenario.nodes.filter((n) => n.kind !== 'decision').map((n) => n.id).join(', ')}`)
+    if (kept.length) say(`Recordings kept in the run folder, not attached to a step and not uploaded: ${kept.join(', ')}. kaloko walk --record records steps for the canvas.`)
+    say('Next: kaloko evaluate, then kaloko preview (local canvas) or kaloko share. Imported screens have no page to check: their deterministic criteria wait for a walk, semantic ones for a person.')
+  },
+
+  /**
+   * `kaloko ci github|gitlab` writes the workflow that walks pull request previews (#15); `kaloko ci preview-url`
+   * runs inside it and finds the preview deployment, the pull request and its base.
+   */
+  async ci (args) {
+    const action = args._[0]
+    if (action === 'preview-url') {
+      const err = (m) => console.error(m)
+      const preview = await findPreview({ wait: Number(args.wait) || 0, say: err })
+      const pr = await pullRequestOf().catch(() => null)
+      if (!preview) throw new UserError('No preview URL found. Set KALOKO_PREVIEW_URL, or let Vercel, Netlify or Cloudflare Pages report deployments to GitHub (the workflow needs deployments: read).')
+      const lines = envLines({ preview, pr })
+      if (args['github-env']) {
+        if (!process.env.GITHUB_ENV) throw new UserError('--github-env works inside GitHub Actions (GITHUB_ENV is not set).')
+        await writeEnvFile(process.env.GITHUB_ENV, lines)
+      }
+      if (typeof args.dotenv === 'string') await writeEnvFile(resolve(args.dotenv), lines)
+      err(`Preview ${preview.url} (from ${preview.source})${pr?.number ? `, pull request #${pr.number}${pr.base ? ` into ${pr.base}` : ''}` : ''}`)
+      console.log(preview.url)
+      return
+    }
+    if (!['github', 'gitlab'].includes(action)) throw new UserError('Usage: kaloko ci github|gitlab [--scenario a.yml,b.yml] [--env preview] [--trigger deployment|pull_request] [--no-affected] [--out file] [--print] [--force]\n       kaloko ci preview-url [--wait 600] [--github-env] [--dotenv file]')
+    const { config, root, file } = await context(args)
+    const envName = typeof args.env === 'string' ? args.env : 'preview'
+    const all = (await scenarioFiles(config, root)).map((f) => relative(root, f))
+    const scenarios = list(args.scenario) || all
+    if (!scenarios.length) throw new UserError('No scenarios to walk: pass --scenario <file>, or list scenario globs in the config.')
+    // the environment the workflow walks: base_url from KALOKO_PREVIEW_URL, which preview-url sets
+    if (!config.environments[envName]) {
+      const text = await readFile(file, 'utf8')
+      const next = addPreviewEnvironment(text, envName)
+      if (next && !args.print) {
+        const problems = (await import('./lib/schema.mjs')).schemaErrors('config.v1', yaml.load(next))
+        if (problems.length) throw new UserError(`Adding ${envName} would make ${CONFIG_FILE} invalid: ${problems.join('; ')}`)
+        await writeFile(file, next)
+        say(`Added the environment ${envName} to ${relative(process.cwd(), file) || CONFIG_FILE}: base_url \${KALOKO_PREVIEW_URL}, set by kaloko ci preview-url in CI.`)
+      } else say(`Add to environments: in ${CONFIG_FILE}:\n  ${envName}:\n    base_url: \${KALOKO_PREVIEW_URL}`)
+    }
+    for (const f of scenarios) {
+      let sc = null
+      try { sc = yaml.load(await readFile(resolve(root, f), 'utf8')) } catch { throw new UserError(`${f} cannot be read.`) }
+      if (sc?.environments && !sc.environments.includes(envName)) say(`! ${f} allows environments [${sc.environments.join(', ')}]: add ${envName}, or kaloko start refuses it in CI.`)
+    }
+    let pkg = null
+    try { pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')) } catch {}
+    const pm = existsSync(join(root, 'pnpm-lock.yaml')) ? 'pnpm' : existsSync(join(root, 'yarn.lock')) ? 'yarn' : existsSync(join(root, 'bun.lockb')) || existsSync(join(root, 'bun.lock')) ? 'bun' : 'npm'
+    const dependency = !!(pkg && ({ ...pkg.dependencies, ...pkg.devDependencies }).kaloko)
+    const version = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8')).version
+    const opts = { scenarios, env: envName, affected: !args['no-affected'], pm, dependency, version: `^${version}`, trigger: args.trigger === 'pull_request' ? 'pull_request' : 'deployment' }
+    const content = action === 'github' ? githubWorkflow(opts) : gitlabJob(opts)
+    if (args.print) { say(content); return }
+    const out = resolve(root, typeof args.out === 'string' ? args.out : action === 'github' ? '.github/workflows/kaloko.yml' : 'kaloko.gitlab-ci.yml')
+    if (existsSync(out) && !args.force) throw new UserError(`${relative(process.cwd(), out)} exists; pass --force to replace it (or --print to compare).`)
+    await mkdir(dirname(out), { recursive: true })
+    await writeFile(out, content)
+    say(`Wrote ${relative(process.cwd(), out)}: ${scenarios.length} scenario(s) on ${envName}${opts.affected ? ', only what each pull request affects' : ''}${action === 'github' ? `, ${opts.trigger === 'deployment' ? 'when a preview deployment succeeds' : 'on every pull request'}` : ''}.`)
+    say(action === 'github'
+      ? 'Next:\n  add the repository secret KALOKO_TOKEN: a token with the tester role and the upload scope (Kaloko → Settings → API tokens; on Enterprise, a service account token)\n  commit the workflow; the first preview deployment of a pull request walks it and comments on the PR\n  Vercel deployment protection: add VERCEL_AUTOMATION_BYPASS_SECRET and uncomment access.headers in the preview environment'
+      : 'Next:\n  include it from .gitlab-ci.yml:  include: { local: kaloko.gitlab-ci.yml }\n  add the masked CI/CD variables KALOKO_TOKEN and KALOKO_GITLAB_TOKEN (api scope, for the merge request comment)\n  make the job wait for your review app deploy (needs:), or set KALOKO_PREVIEW_URL in its variables')
+  },
+
   async auth (args) {
     const { config, root } = await context(args)
     const action = args._[0]
@@ -1006,9 +1373,16 @@ const commands = {
       await writeFile(join(run.dir, 'meta.json'), JSON.stringify(meta, null, 2) + '\n')
       return
     }
-    const manifest = await buildManifest({ run, scenario, config, root, catalog: [] })
+    let manifest = await buildManifest({ run, scenario, config, root, catalog: [] })
     await writePreview({ run, manifest })
-    const files = new Set()
+    // the plan and storage before anything is sent; recordings travel on plans with the recordings feature only
+    const u = await client.request('GET', `/orgs/${config.org}/usage`).catch(() => null)
+    const recs = recordingFiles(manifest)
+    if (recs.length && u?.limits?.features && !u.limits.features.recordings) {
+      manifest = stripRecordings(manifest)
+      say(`Recordings stay in the local preview (${recs.length} file(s)): sharing them is part of the Business plan and up, and this organization is on ${u.limits.plan_name}. Screenshots and traces are shared as usual.`)
+    }
+    const files = new Set([...traceFiles(manifest), ...recordingFiles(manifest)])
     for (const n of manifest.nodes) {
       for (const byVp of Object.values(n.captures || {})) for (const c of Object.values(byVp)) [c.image || c.png, c.thumb, c.html, c.eval, c.tree, c.spec].filter(Boolean).forEach((p) => files.add(p))
       for (const a of n.attachments || []) files.add(a.file)
@@ -1020,39 +1394,31 @@ const commands = {
       }
     }
     const days = Number(args.expires) || config.share?.expires_days || 30
-    const { stat } = await import('node:fs/promises')
-    let total = 0
-    for (const p of files) total += (await stat(join(run.dir, p))).size
+    // by content hash (#28): files the organization already stores (earlier runs, an interrupted share) are not sent
+    let entries = await hashFiles(run.dir, [...files])
+    // a recording above the service's file limit stays local (with its poster and preview), the rest is shared
+    const tooBig = new Set(entries.filter((e) => /\.rec\./.test(e.path) && u?.limits?.max_file_bytes && e.bytes > u.limits.max_file_bytes).map((e) => e.path))
+    if (tooBig.size) {
+      manifest = withoutRecordings(manifest, tooBig)
+      const keep = new Set([...traceFiles(manifest), ...recordingFiles(manifest)])
+      entries = entries.filter((e) => !/\.rec\./.test(e.path) || keep.has(e.path))
+      say(`${tooBig.size} recording(s) larger than ${fmtBytes(u.limits.max_file_bytes)} stay in the local preview: ${[...tooBig].slice(0, 3).join(', ')}${tooBig.size > 3 ? ', …' : ''}. Record them with record.quality: low or a lower max_seconds to share them.`)
+    }
+    const missing = await missingHashes(client, config.org, entries.map((e) => e.hash))
+    const total = entries.reduce((n, e) => n + e.bytes, 0)
+    const fresh = missing ? [...new Map(entries.filter((e) => missing.has(e.hash)).map((e) => [e.hash, e.bytes])).values()].reduce((n, b) => n + b, 0) : total
+    const resumed = (await readJson(join(run.dir, PROGRESS_FILE), null).catch(() => null))?.run === manifest.id
     try {
-      const u = await client.request('GET', `/orgs/${config.org}/usage`)
+      if (!u) throw new Error('usage unavailable')
       if (total > u.limits.max_run_bytes) throw new UserError(`This run is ${fmtBytes(total)}; the limit per run is ${fmtBytes(u.limits.max_run_bytes)}. Capture fewer viewports or locales, or ask an admin for a higher limit.`)
-      if (u.usage.bytes + total > u.limits.quota_bytes) throw new UserError(`Storage quota would be exceeded: ${fmtBytes(u.usage.bytes)} used + ${fmtBytes(total)} > ${fmtBytes(u.limits.quota_bytes)}. Delete old runs in Settings or ask for a higher quota.`)
-      say(`Uploading ${files.size} files, ${fmtBytes(total)} (organization uses ${fmtBytes(u.usage.bytes)} of ${fmtBytes(u.limits.quota_bytes)})`)
+      if (u.usage.bytes + fresh > u.limits.quota_bytes) throw new UserError(`Storage quota would be exceeded: ${fmtBytes(u.usage.bytes)} used + ${fmtBytes(fresh)} > ${fmtBytes(u.limits.quota_bytes)}. Delete old runs in Settings or ask for a higher quota.`)
+      const recBytes = entries.filter((e) => /\.rec\./.test(e.path)).reduce((n, e) => n + e.bytes, 0)
+      say(`${resumed ? 'Resuming the interrupted share: ' : ''}${files.size} files, ${fmtBytes(total)}${recBytes ? ` (recordings ${fmtBytes(recBytes)})` : ''}${missing ? `; ${fmtBytes(fresh)} new, the rest already stored` : ''} (organization uses ${fmtBytes(u.usage.bytes)} of ${fmtBytes(u.limits.quota_bytes)})`)
     } catch (e) { if (e instanceof UserError && /limit|quota/.test(e.message)) throw e }
     const created = await client.request('POST', `/orgs/${config.org}/runs?expires_days=${days}`, manifest)
-    // text files travel and rest gzip-compressed; the service serves them with Content-Encoding: gzip
-    const body = async (p) => { const raw = await readFile(join(run.dir, p)); const gz = /\.(html|json)$/.test(p) && raw.length > 512; return { data: gz ? gzipSync(raw, { level: 6 }) : raw, gz } }
-    // the file list goes first: the service checks limits once and each upload is then a plain write
-    // (an older service without the plan answers 404/405 and every upload checks itself, as before)
-    // screenshots name their SHA-256: the service checks it on arrival and compares unchanged steps with it
-    if (files.size) {
-      const plan = []
-      for (const p of files) { const { data } = await body(p); plan.push({ path: p, bytes: data.length, ...(/\.(png|webp|jpe?g)$/i.test(p) ? { sha256: createHash('sha256').update(data).digest('hex') } : {}) }) }
-      await client.request('POST', `/orgs/${config.org}/runs/${manifest.id}/files`, { files: plan }).catch((e) => { if (!/HTTP (404|405)/.test(e.message)) throw e })
-    }
-    const queue = [...files]
-    let done = 0
-    const worker = async () => {
-      while (queue.length) {
-        const p = queue.shift()
-        const { data, gz } = await body(p)
-        await client.upload(`/orgs/${config.org}/runs/${manifest.id}/files/${p.split('/').map(encodeURIComponent).join('/')}`, data, p, gz ? { 'Content-Encoding': 'gzip' } : {})
-        done++
-        if (done % 10 === 0 || done === files.size) process.stdout.write(`\r  uploaded ${done}/${files.size}`)
-      }
-    }
-    await Promise.all(Array.from({ length: files.size > 200 ? 12 : 6 }, worker))
-    if (files.size) process.stdout.write('\n')
+    await writeFile(join(run.dir, PROGRESS_FILE), JSON.stringify({ run: manifest.id, started_at: new Date().toISOString() }) + '\n').catch(() => {})
+    const up = await uploadRunFiles({ client, org: config.org, runId: manifest.id, dir: run.dir, entries, missing, say })
+    if (up.mode === 'blobs') say(`  ${up.uploaded} new file(s) sent (${fmtBytes(up.bytes)}), ${up.reused} unchanged file(s) reused`)
     // experimental HTML views (#42): their bundles travel as blobs and attach to the run as revisions
     const viewIds = new Set(manifest.nodes.flatMap((n) => Object.values(n.captures || {}).flatMap((vps) => Object.values(vps).map((c) => c.view?.revision).filter(Boolean))))
     if (viewIds.size) {
@@ -1067,6 +1433,7 @@ const commands = {
       } catch (e) { say(`HTML views not attached: ${e.message.split('\n')[0]}`) }
     }
     const fin = await client.request('POST', `/orgs/${config.org}/runs/${manifest.id}/finalize`)
+    await rm(join(run.dir, PROGRESS_FILE), { force: true })
     const meta = await readJson(join(run.dir, 'meta.json'))
     meta.shared = { url: fin.url, at: new Date().toISOString(), expires_days: created.expires_days }
     await writeFile(join(run.dir, 'meta.json'), JSON.stringify(meta, null, 2) + '\n')