kaloko 0.5.1 → 0.6.0

package/src/cli.mjs

@@ -36,6 +36,7 @@ import { upsertPrComment } from './lib/pr.mjs'
 import { formatReviewQueue, shareReviewLine } from './lib/review.mjs'
 import { htmlViewAllowed } from './lib/htmlview.mjs'
 import { service, serviceUrl } from './lib/service.mjs'
+import { issueCmd, scheduleCmd } from './lib/integrations-cli.mjs'
 import { login } from './lib/login.mjs'
 import { initNextSteps, loginNextSteps } from './lib/onboarding.mjs'
 import { specCmd, driftCmd } from './lib/spec-cli.mjs'
@@ -45,7 +46,8 @@ 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 { walkDesign, syncDesign, publishVersion, previewNotes, historyCmd, referenceCmd, tokensCmd, exportLive, localRevisions, branchCmd, uploadBlobs } from './lib/design-cli.mjs'
+import { screensCmd } from './lib/screens-cli.mjs'
 import { designDir, readBase, headKey } from './lib/design.mjs'
 import { lintDesign, formatLint } from './lib/design-lint.mjs'
 import { exportDesign } from './lib/design-export.mjs'
@@ -69,15 +71,21 @@ 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>] [--no-detect] [--no-scenario]
+  init [--agent claude|codex|all] [--org <slug>] [--no-detect] [--no-scenario] [--docs=off|changelog|full]
                                     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
+                                    (qa/flows/main-pages.yml) when the project has none; asks "Keep a visual changelog?"
+                                    (--docs: changelog adds CHANGELOG.md and the config block, full also docs/ folders
+                                    with Diátaxis templates: tutorials, how-to, reference, explanation)
   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 github --release [--snippet] [--print] [--force]
+                                    Write .github/workflows/kaloko-release.yml: when release-please, changesets or
+                                    semantic-release publishes a GitHub release, kaloko release records it on Kaloko
+                                    (--snippet prints the step to add after the tool's own step instead)
   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
@@ -227,10 +235,60 @@ Results
   stability --pull [--scenario id] [--json]
                                     Regions people drew on screenshots on kaloko.app (step detail → Page → Draw a
                                     region) go into the scenario's ignore: of their steps; walk them again after
+  screens [words] [--project p] [--product p] [--module m] [--scenario id] [--locale l] [--viewport v] [--device d]
+          [--status pass|partial|fail|skip] [--environment e] [--designs] [--all] [--json] [--cursor c]
+                                    The screen library: the newest screenshot of every step across your flows, searched
+                                    by title, text, URL or id, with the canvas link of each (--designs adds design versions)
   compare [--run id] [--baseline id | --design] [--json]
                                     Text diff of two runs: step statuses, criterion verdicts, scores and evidence
                                     (default: current run against the scenario baseline, else the previous run)
 
+Jira and Linear (connected by an admin in Settings → Integrations)
+  issue create --step <id> --to jira|linear [--criterion AC2] [--title "…"] [--note "…"] [--run id] [--json]
+                                    An issue from a returned step or a failing criterion: the screenshot, the
+                                    criterion, the reviewers' notes and a link back; the step's comment is resolved
+                                    when the issue is done. Branches and PR titles that name a key (WEB-12) link runs
+  issue list [--run id] [--scenario id] [--state open|done|canceled] [--json]
+
+Hosted runs (read-only scenarios on Kaloko's browsers, Business plan)
+  schedule add --scenario <file> --env <name> [--every day|week|manual] [--at 5] [--weekday mon] [--account key]
+                                    Kaloko opens the scenario's pages every day or week (hour in UTC) and shares the
+                                    run as you: public pages, HTTP Basic from the environment, or a saved session
+                                    (--account). Steps that click or type are left out; they need the full walk
+  schedule list | run <id> | pause <id> | resume <id> | remove <id> [--json]
+  schedule export github --scenario <file> --env <name> [--every day|week] [--at 5] [--out file] [--print]
+                                    A GitHub Actions workflow that walks the scenario on a schedule with the full CLI
+
+Changelog (Keep a Changelog in CHANGELOG.md; pictures are step references kaloko:<scenario>/<step>)
+  changelog draft [--product p] [--since <tag|version>] [--apply] [--json] [--offline]
+                                    The Unreleased entry since the last release: merged pull requests and commits
+                                    (Conventional Commits when used, gh for titles) grouped Added / Changed / Fixed /
+                                    Removed, plus before/after pictures of the screens accepted runs show differently;
+                                    printed, or --apply writes it into CHANGELOG.md (not when a release tool owns it)
+  release [<version>] [--product p] [--date YYYY-MM-DD] [--runs id,id] [--no-write] [--no-docs] [--dry-run] [--json]
+                                    Record a release on Kaloko: the version (default: from git tags, package.json,
+                                    release-please or changesets), its CHANGELOG.md entry (Unreleased becomes the
+                                    version unless --no-write) and the accepted runs that are its pictures; prints the
+                                    illustrated changelog page. The docs folder is published as that version's docs
+                                    (Business) unless --no-docs
+
+Docs (Markdown in docs/ with step references; Diátaxis folders; translations as guide.cs.md next to guide.md)
+  docs publish [--product p] [--version latest|<v>] [--reviewed] [--dry-run] [--json]
+                                    Send the docs folder to Kaloko as the docs of a version (default latest): readers
+                                    get a version selector, language and screen switches, search and training mode;
+                                    --reviewed says the text was checked, which clears its stale notes
+  docs check [--product p] [--version v] [--offline] [--strict] [--json]
+                                    Broken or unknown step references, stale sections (the screen changed since the
+                                    text was published), missing or outdated translations and user-visible changelog
+                                    items without a picture; exit 1 on references or stale sections (--strict: on
+                                    anything)
+  export --format md|docusaurus|vitepress|mkdocs|html|pdf|json [--product p] [--version v] [--lang l]
+       [--what all|docs|changelog] [--local] [--out dir|file]
+                                    The docs and changelog with their pictures as files: Markdown with an assets
+                                    folder, a Docusaurus, VitePress or MkDocs folder with sidebars, offline HTML, PDF
+                                    (printed by the browser) or the changelog as JSON; --local exports the files in
+                                    the repository instead of the published ones
+
 Design (environments with kind: design; live HTML steps in a folder)
   start --scenario <file> --env <design env>   A run of the design folder (same scenario as development and QA)
   walk [--steps a,b] [--no-cache]   Render the steps; unchanged revisions reuse their captures
@@ -241,7 +299,15 @@ Design (environments with kind: design; live HTML steps in a folder)
   design lint [--env e | --dir design/] [--scenario file] [--all] [--strict] [--json]
                                     Check the folder against the portable HTML rules (relative URLs, no CDNs, no storage,
                                     deterministic content, viewport, lang, links that also work from disk); --strict fails on warnings
-  share [--name <text>] [--branch b]  Publish the draft as a version of the flow (a run): "v4 · 3 changed, 17 unchanged"
+  share [--name <text>] [--branch b] [--notes file|-] [--notes-preview]
+                                    Publish the draft as a version of the flow (a run): "v4 · 3 changed, 17 unchanged",
+                                    with "what changed" notes per step (screens per viewport, text, tokens); --notes-preview
+                                    prints them without publishing, --notes replaces them (a summary, then "step: text" lines)
+  design import figma <file-url|key|export folder> [--scenario file] [--frames a,b] [--page p] [--map frames.json]
+       [--token-env FIGMA_TOKEN] [--tokens auto|write|skip] [--force] [--dry-run] [--publish [--notes file]]
+                                    Figma frames become design steps (frame PNG at 1× and 2×, text layers with their
+                                    typography, variables or styles as tokens.json) matched to steps by name or --map;
+                                    a folder exported from Figma works without a token. One way: no prototype links
   history [--scenario id] [--step id] [--locale l] [--json]
                                     Versions of the flow; revisions of a step with who (person or agent) and when
   spec [step] [--ref design|draft|vN|<run id>] [--locale l] [--viewport v] [--local] [--json]
@@ -381,6 +447,49 @@ function stepOf (scenario, id) {
 }
 
 /** Scenario of --scenario (id or file) or of the current run. */
+/**
+ * kaloko design import figma <file-url|key|folder>: Figma frames (or a folder exported from Figma) become the steps of
+ * the design folder; --publish then walks them and publishes a version (the design reference to be).
+ */
+async function designImport (args) {
+  const [, kind, source] = args._
+  if (kind !== 'figma' || !source) throw new UserError('Usage: kaloko design import figma <file-url|key|export folder> [--scenario file] [--env <design env>] [--frames a,b] [--page name] [--map frames.json|yml] [--token-env FIGMA_TOKEN] [--tokens auto|write|skip] [--force] [--dry-run] [--publish [--notes file]]')
+  const { config, root } = await context(args)
+  let run = null
+  try { run = await resolveRun({ root, output: config.output, run: args.run }) } catch {}
+  const runEnv = run ? environment(config, run.meta.environment.name) : null
+  const env = typeof args.env === 'string' ? environment(config, args.env) : runEnv?.kind === 'design' ? runEnv : Object.keys(config.environments).map((n) => environment(config, n)).find((e) => e.kind === 'design')
+  if (!env || env.kind !== 'design') throw new UserError('No design environment: add one with kind: design and serve: design/ to kaloko.config.yml, or pass --env <design env>.')
+  const scenarioFile = typeof args.scenario === 'string' ? resolve(args.scenario) : run && runEnv?.kind === 'design' ? resolve(root, run.meta.scenario_file) : null
+  if (!scenarioFile) throw new UserError('Name the scenario whose steps the frames are: --scenario <file>.')
+  const scenario = await loadScenario(scenarioFile)
+  const { importFigma, formatImport, readMap } = await import('./lib/figma.mjs')
+  const scope = startScope({ args: {}, scenario, config, env })
+  const viewports = Object.fromEntries(baseViewports(scope).map((v) => [v, scope.viewports[v]]))
+  const tokenVar = typeof args['token-env'] === 'string' ? args['token-env'] : typeof args.token === 'string' && /^[A-Z_][A-Z0-9_]*$/.test(args.token) ? args.token : 'FIGMA_TOKEN'
+  const dir = typeof args.dir === 'string' ? resolve(args.dir) : designDir(env, root)
+  const r = await importFigma({
+    source, scenario, viewports, locales: scenario.locales || ['default'], dir,
+    token: process.env[tokenVar] || (tokenVar === 'FIGMA_TOKEN' ? process.env.FIGMA_ACCESS_TOKEN : null) || null,
+    map: typeof args.map === 'string' ? await readMap(resolve(args.map)) : null, only: list(args.frames), page: typeof args.page === 'string' ? args.page : null,
+    tokensMode: ['write', 'skip'].includes(args.tokens) ? args.tokens : 'auto', force: !!args.force, dryRun: !!args['dry-run'], say
+  })
+  if (args.json) say(JSON.stringify(r, null, 2))
+  else say(formatImport(r, { dir: relative(process.cwd(), dir) || '.' }))
+  if (args['dry-run']) return r
+  const lint = await lintDesign({ dir, scenario })
+  if (lint.errors) say(`\n${formatLint(lint, { max: 10 })}`)
+  if (!args.publish) {
+    say(`\nNext: kaloko start --scenario ${relative(process.cwd(), scenarioFile)} --env ${env.name} && kaloko walk && kaloko share (or rerun with --publish).\nAccept the version on the canvas and set it as the design reference (kaloko reference --design --version <n>): implementation runs with packs: [design] are then checked against these frames.`)
+    return r
+  }
+  await commands.start({ ...args, _: [], scenario: scenarioFile, env: env.name })
+  const current = await resolveRun({ root, output: config.output })
+  await commands.walk({ _: [], run: current.dir })
+  await commands.share({ _: [], run: current.dir, ...(typeof args.notes === 'string' ? { notes: args.notes } : {}), ...(typeof args.name === 'string' ? { name: args.name } : {}), ...(typeof args.branch === 'string' ? { branch: args.branch } : {}) })
+  return r
+}
+
 async function scenarioIdOf (args, config, root) {
   if (typeof args.scenario === 'string') {
     if (/\.ya?ml$/.test(args.scenario)) return (await loadScenario(resolve(args.scenario))).id
@@ -773,6 +882,38 @@ const commands = {
       await writeFile(file, tpl)
       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.`)
+    // the visual changelog (docs/DOCS-CHANGELOG.md): asked once; --docs=off|changelog|full for scripts and agents
+    let docsMode = typeof args.docs === 'string' ? args.docs : null
+    if (docsMode && !['off', 'changelog', 'full'].includes(docsMode)) throw new UserError('--docs must be off, changelog or full.')
+    if (!docsMode && process.stdin.isTTY && process.stdout.isTTY && !process.env.CI && !process.env.NODE_TEST_CONTEXT) {
+      const rl = (await import('node:readline/promises')).createInterface({ input: process.stdin, output: process.stdout })
+      const a = (await rl.question('Keep a visual changelog? (recommended) [Y/n] ')).trim().toLowerCase(); rl.close()
+      docsMode = a === 'n' || a === 'no' ? 'off' : 'changelog'
+    }
+    if (docsMode && docsMode !== 'off') {
+      const { docsConfigBlock, detectProducts, DOCS_SKELETON } = await import('./lib/changelog.mjs')
+      const { CHANGELOG_SKELETON } = await import('./lib/changelog-core.mjs')
+      const { mkdir: mkdirp } = await import('node:fs/promises')
+      const cfgFile = existsSync(file) ? file : join(cwd, LEGACY_CONFIG_FILE)
+      const cfg = await readFile(cfgFile, 'utf8')
+      const products = /^products:/m.test(cfg) ? [] : await detectProducts(cwd)
+      if (!/^docs:/m.test(cfg) && !/^products:/m.test(cfg)) { await writeFile(cfgFile, `${cfg.replace(/\n*$/, '\n')}${docsConfigBlock({ products, full: docsMode === 'full' })}`); say(`Added the changelog settings to ${relative(cwd, cfgFile)}${products.length ? ` with ${products.length} products (${products.map((p) => p.slug).join(', ')})` : ''}`) }
+      for (const f of products.length ? products.map((p) => join(cwd, p.dir, 'CHANGELOG.md')) : [join(cwd, 'CHANGELOG.md')]) {
+        if (existsSync(f)) continue
+        await mkdirp(dirname(f), { recursive: true })
+        await writeFile(f, CHANGELOG_SKELETON)
+        say(`Created ${relative(cwd, f)} (Keep a Changelog; kaloko changelog draft fills Unreleased, kaloko release records a version)`)
+      }
+      if (docsMode === 'full') {
+        for (const [rel, text] of Object.entries(DOCS_SKELETON)) {
+          const f = join(cwd, rel)
+          if (existsSync(f)) continue
+          await mkdirp(dirname(f), { recursive: true })
+          await writeFile(f, text)
+        }
+        say('Docs folders in docs/ (tutorials, how-to, reference, explanation) with an index and a template in each; kaloko docs publish sends them, kaloko docs check checks them')
+      }
+    } else if (!docsMode) say('Visual changelog: kaloko init --docs=changelog adds CHANGELOG.md and the config block (recommended).')
     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.')
     const { cp, mkdir, appendFile, rm } = await import('node:fs/promises')
@@ -875,9 +1016,11 @@ const commands = {
     const vpNames = baseViewports(scope)
     const git = await gitMeta(root)
     const executor = { kind: args.executor ? 'agent' : 'cli', name: args.executor || 'kaloko-cli' }
-    const { project, issue } = await projectAndIssue({ cwd: root, config, scenario, branch: git?.branch })
+    const { project, issue } = await projectAndIssue({ cwd: root, config, scenario, branch: git?.branch, title: git?.pr?.title || null })
     const appVer = typeof args['app-version'] === 'string' ? args['app-version'].slice(0, 80) : await appVersion(root)
-    const { dir, meta } = await createRun({ output: config.output, scenario, scenarioFile, env, scope, git, executor, root, project, issue, appVersion: appVer })
+    // the product the flow documents (visual changelog): its tag, or the only product of the config
+    const product = scenario.product || (Object.keys(config.products || {}).length === 1 ? Object.keys(config.products)[0] : null)
+    const { dir, meta } = await createRun({ output: config.output, scenario, scenarioFile, env, scope, git, executor, root, project, issue, appVersion: appVer, product })
     say(`Run ${meta.id}\n  dir: ${relative(process.cwd(), dir)}\n  env: ${env.name}${env.readonly ? ' (readonly)' : ''}\n  locales: ${locales.join(', ')}  viewports: ${vpNames.length > 12 ? `${vpNames.slice(0, 12).join(', ')} … (${vpNames.length})` : vpNames.join(', ')}${dimensionLine(scope)}\n  project: ${project.slug}${issue ? `  issue: ${issue.repo ? issue.repo + '#' : '#'}${issue.number}` : ''}`)
     const addr = recipient(env.mail, meta.short)
     if (addr) say(`  test e-mail: ${addr}`)
@@ -1343,8 +1486,32 @@ const commands = {
       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]')
+    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 github --release [--snippet] [--print] [--force]\n       kaloko ci preview-url [--wait 600] [--github-env] [--dotenv file]')
     const { config, root, file } = await context(args)
+    if (args.release) {
+      // release-tool integrations: record each published release on Kaloko (docs/DOCS-CHANGELOG.md)
+      if (action !== 'github') throw new UserError('--release writes a GitHub Actions workflow; on GitLab run kaloko release <version> --no-write in your release job.')
+      const { productsOf, detectVersionSource } = await import('./lib/changelog.mjs')
+      const { releaseWorkflow, releaseSnippet } = await import('./lib/ci.mjs')
+      const products = productsOf(config, root)
+      const sources = await Promise.all(products.map((p) => detectVersionSource(root, p)))
+      const tool = sources.map((s) => s.tool).find(Boolean) || null
+      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}`
+      if (args.snippet) { say(releaseSnippet({ tool, pm, dependency, version, product: products.length > 1 ? '<product>' : null })); return }
+      const content = releaseWorkflow({ products: products.map((p, i) => ({ slug: products.length > 1 || !p.implicit ? p.slug : null, pattern: sources[i].pattern || 'v*' })), pm, dependency, version, tool })
+      if (args.print) { say(content); return }
+      const out = resolve(root, typeof args.out === 'string' ? args.out : '.github/workflows/kaloko-release.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)}: every published GitHub release${tool ? ` (${tool} publishes them)` : ''} is recorded on Kaloko with its changelog entry, pictures and docs.`)
+      say('Next:\n  add the repository secret KALOKO_TOKEN (tester role, upload scope)\n  publish releases with your release tool as before; nothing else changes in your release workflow')
+      return
+    }
     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
@@ -1521,6 +1688,7 @@ const commands = {
     if (env.kind === 'design') {
       const r = await syncDesign({ config, root, run, scenario, env, client, args: { ...args, strict: true }, say, pull: false, render: (steps) => walkDesign({ config, root, run, scenario, env, pick: steps, locales: run.meta.scope.locales, viewports: run.meta.scope.viewports, say }).then(() => evaluateRun({ run, scenario, config, root })) })
       if (r.conflicts) return
+      if (args['notes-preview']) { await previewNotes({ config, scenario, client, args, say }); return }
       const v = await publishVersion({ config, scenario, client, args, say })
       const meta = await readJson(join(run.dir, 'meta.json'))
       meta.shared = { url: v.url, at: new Date().toISOString(), version: v.version, run: v.id }
@@ -1616,7 +1784,8 @@ const commands = {
   },
 
   async design (args) {
-    if (args._[0] !== 'lint') throw new UserError('Usage: kaloko design lint [--env <design env> | --dir design/] [--scenario file] [--all] [--strict] [--json]')
+    if (args._[0] === 'import') return designImport(args)
+    if (args._[0] !== 'lint') throw new UserError('Usage: kaloko design lint [--env <design env> | --dir design/] [--scenario file] [--all] [--strict] [--json]\n       kaloko design import figma <file-url|key|export folder> [--frames a,b] [--map frames.json] [--token-env FIGMA_TOKEN] [--publish]')
     const { config, root } = await context(args)
     let run = null
     try { run = await resolveRun({ root, output: config.output, run: args.run }) } catch {}
@@ -1633,6 +1802,12 @@ const commands = {
     if (report.errors || (args.strict && report.warnings)) process.exitCode = 1
   },
 
+  /** `kaloko screens [words]`: the screen library of the organization (newest capture of every step). */
+  async screens (args) {
+    const { config } = await context(args)
+    await screensCmd({ config, client: service(config), args, say })
+  },
+
   async history (args) {
     const { config, root } = await context(args)
     const scenarioId = await scenarioIdOf(args, config, root)
@@ -1734,6 +1909,20 @@ const commands = {
    * The signed acceptance record of an accepted run: JSON and PDF downloaded and checked against the service's public
    * key; --verify checks a record someone handed over (no token, no project needed).
    */
+  /** Jira and Linear (#21): an issue from a step of a shared run, and the issues created so far. */
+  async issue (args) {
+    const { config, root } = await context(args)
+    let runId = null
+    if (args._[0] === 'create' && typeof args.run !== 'string') { try { const r = await resolveRun({ root, output: config.output }); if (r.meta.shared) runId = r.meta.id } catch {} }
+    return issueCmd({ args, config, client: service(config), runId, say })
+  },
+
+  /** Hosted runs (#16): schedules of read-only scenarios on Kaloko's browsers, or a scheduled GitHub workflow. */
+  async schedule (args) {
+    const { config, root } = await context(args)
+    return scheduleCmd({ args, config, root, say, deps: { loadScenario, environment, baseUrl, projectAndIssue, packageRoot, service } })
+  },
+
   async signoff (args) {
     if (typeof args.verify === 'string') {
       const config = await context(args).then((c) => c.config).catch(() => ({}))
@@ -1992,6 +2181,27 @@ const commands = {
       return
     }
     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.')
+      const { pickProduct } = await import('./lib/changelog.mjs')
+      const { exportDocs } = await import('./lib/docs.mjs')
+      const product = pickProduct(config, root, args.product)
+      const printPdf = async (htmlFile, outFile) => {
+        const { chromium } = await import('playwright')
+        const browser = await chromium.launch(config.browser?.channel ? { channel: config.browser.channel } : {}).catch(() => chromium.launch())
+        try {
+          const page = await browser.newPage()
+          await page.goto(pathToFileURL(htmlFile).href, { waitUntil: 'load', timeout: 60000 })
+          await page.pdf({ path: outFile, format: 'A4', printBackground: true, margin: { top: '16mm', bottom: '16mm', left: '14mm', right: '14mm' } })
+        } finally { await browser.close() }
+      }
+      const r = await exportDocs({ root, config, product, client, format: args.format, version: typeof args.version === 'string' ? args.version : 'latest', lang: typeof args.lang === 'string' ? args.lang : null, what: ['docs', 'changelog'].includes(args.what) ? args.what : 'all', out: typeof args.out === 'string' ? resolve(args.out) : null, local: !!args.local, printPdf: args['server-pdf'] ? null : printPdf, say })
+      if (r.kind === 'file') { say(`Exported ${product.slug} as ${r.format} → ${relative(process.cwd(), r.file) || r.file}`); return }
+      const m = r.manifest
+      say(`Exported ${product.slug} ${m?.version || ''} as ${r.format} → ${relative(process.cwd(), r.dir) || r.dir}\n  ${m ? `${m.pages} page(s), ${m.releases} release(s), ${m.pictures} picture(s)` : `${r.files} file(s)`}${m?.missing?.length ? `\n  ! no accepted picture for: ${m.missing.slice(0, 8).join(', ')}${m.missing.length > 8 ? ' …' : ''}` : ''}`)
+      return
+    }
     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).')
@@ -2019,12 +2229,96 @@ const commands = {
     const { config, root, file } = await context(args)
     // engines the scenarios ask for (browsers: [webkit, firefox]), so doctor checks they are installed
     const engines = []
-    for (const f of await scenarioFiles(config, root).catch(() => [])) { try { engines.push(...((yaml.load(await readFile(f, 'utf8')) || {}).browsers || [])) } catch {} }
-    const r = await doctor({ config, root, file, fix: !!args.fix, engines })
+    const scenarios = []
+    for (const f of await scenarioFiles(config, root).catch(() => [])) { try { const s = yaml.load(await readFile(f, 'utf8')) || {}; engines.push(...(s.browsers || [])); scenarios.push({ file: relative(root, f), product: s.product || null, module: s.module || null }) } catch {} }
+    const r = await doctor({ config, root, file, fix: !!args.fix, engines, scenarios })
     say(args.json ? JSON.stringify(r, null, 2) : formatDoctor(r))
     if (!r.ok) process.exitCode = 1
   },
 
+  /** `kaloko changelog draft`: the Unreleased entry from merged work and the screens accepted runs show differently. */
+  async changelog (args) {
+    const sub = args._[0]
+    if (sub !== 'draft') throw new UserError('Usage: kaloko changelog draft [--product p] [--since <tag|version>] [--apply] [--json] [--offline]')
+    const { config, root } = await context(args)
+    const { pickProduct, draftChangelog, draftText, applyToChangelog } = await import('./lib/changelog.mjs')
+    const product = pickProduct(config, root, args.product)
+    let client = null
+    if (!args.offline) { try { client = service(config) } catch {} }
+    const d = await draftChangelog({ root, config, product, since: typeof args.since === 'string' ? args.since : null, client })
+    if (args.json) { say(JSON.stringify(d, null, 2)); return }
+    const pictures = d.changes.reduce((n, s) => n + (s.steps?.length || 0), 0)
+    const head = `${product.slug}: ${d.commits} change(s) since ${d.since.ref || 'the first commit'}${d.service === 'ok' ? `, ${pictures} changed screen(s) in accepted runs since ${d.previous ? `release ${d.previous.version}` : 'the first accepted runs'}` : d.service === 'offline' ? ' (no service: pictures of changed screens need a token)' : ` (service: ${d.service})`}; ${d.internal.length} internal left out.`
+    if (args.apply) {
+      const r = await applyToChangelog(d)
+      say(`${head}\n${r.created ? 'Created' : 'Updated'} ${relative(process.cwd(), d.file) || d.file}: ${r.added} new item(s) in Unreleased. Edit them for people, then kaloko release <version>.`)
+      return
+    }
+    console.error(head)
+    say(draftText(d))
+  },
+
+  /** `kaloko docs publish|check`: the docs folder on Kaloko per version, and what in it needs attention. */
+  async docs (args) {
+    const sub = args._[0]
+    if (!['publish', 'check'].includes(sub)) throw new UserError('Usage: kaloko docs publish [--product p] [--version latest|<v>] [--reviewed] [--dry-run] [--json]\n       kaloko docs check [--product p] [--version v] [--offline] [--strict] [--json]')
+    const { config, root } = await context(args)
+    const { pickProduct } = await import('./lib/changelog.mjs')
+    const docs = await import('./lib/docs.mjs')
+    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.')
+      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 }
+      const lines = [`${product.slug} docs ${r.version}: ${r.pages} page(s) from ${r.dir}, ${r.changed} changed, ${r.unchanged} unchanged${r.removed ? `, ${r.removed} removed` : ''}${args.reviewed ? ' (marked as checked)' : ''}`, `  ${r.url}`]
+      for (const b of r.broken_refs || []) lines.push(`  ! broken step reference in ${b.path || 'index'}${b.lang ? ` (${b.lang})` : ''}: ${b.ref}`)
+      for (const u of (r.unresolved || []).slice(0, 10)) lines.push(`  ! no accepted picture yet: ${u.ref} (${u.path || 'index'})`)
+      for (const n of r.notes || []) lines.push(`  ! ${n}`)
+      say(lines.join('\n'))
+      return
+    }
+    // check: the scenario files say which steps exist
+    const scenarios = new Map()
+    for (const f of await scenarioFiles(config, root).catch(() => [])) { try { const s = yaml.load(await readFile(f, 'utf8')) || {}; if (s.id) scenarios.set(String(s.id), new Set((s.nodes || []).map((n) => String(n.id)))) } catch {} }
+    let client = null
+    if (!args.offline) { try { client = service(config) } catch {} }
+    const r = await docs.docsCheck({ root, config, product, client, scenarios: scenarios.size ? scenarios : null, version })
+    say(args.json ? JSON.stringify(r, null, 2) : docs.formatCheck(r))
+    if (!r.ok || (args.strict && r.warnings)) process.exitCode = 1
+  },
+
+  /** `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.')
+    const { pickProduct, releaseProduct } = await import('./lib/changelog.mjs')
+    const product = pickProduct(config, root, args.product)
+    const client = args['dry-run'] ? null : service(config)
+    const r = await releaseProduct({ root, config, product, version: args._[0] || null, date: typeof args.date === 'string' ? args.date : null, client, write: !args['no-write'], runs: list(args.runs), dryRun: !!args['dry-run'] })
+    // the docs of this version: what the docs folder says now (Business; latest stays as kaloko docs publish left it)
+    if (r.release && !args['no-docs']) {
+      const docs = await import('./lib/docs.mjs')
+      const pages = await docs.collectDocs(root, product).then((x) => x.pages.length).catch(() => 0)
+      if (pages) {
+        try { r.docs = await docs.publishDocs({ root, config, product, client, version: r.version }) } catch (e) { r.docs = { error: String(e.message || e).split('\n')[0] } }
+      }
+    }
+    if (args.json) { say(JSON.stringify(r, null, 2)); return }
+    const file = relative(process.cwd(), r.file) || r.file
+    const lines = [`${product.slug} ${r.version} (${r.date}) · version source: ${r.source.tool || r.source.source}${r.source.path ? ` (${r.source.path})` : ''}`]
+    lines.push(r.section ? `  ${file}: ${r.finalized ? 'Unreleased became' : 'entry'} ${r.version}, ${r.items} item(s), ${r.refs} picture reference(s)` : `  ${file}: no entry for ${r.version}`)
+    if (r.release) {
+      lines.push(`  ${r.release.created ? 'Recorded' : 'Updated'} on the service with ${r.release.runs.length} reference run(s)${r.release.versioned_runs ? `; ${r.release.versioned_runs} accepted run(s) now carry ${r.version}` : ''}`)
+      lines.push(`  ${r.release.url}`)
+    } else lines.push('  Dry run: nothing sent.')
+    if (r.docs) lines.push(r.docs.error ? `  ! Docs of ${r.version} not published: ${r.docs.error}` : `  Docs of ${r.version}: ${r.docs.pages} page(s)${r.docs.changed ? `, ${r.docs.changed} changed since the last publish of ${r.version}` : ''}`)
+    for (const n of r.notes) lines.push(`  ! ${n}`)
+    if (r.finalized) lines.push(`  Commit ${file} with the release.`)
+    say(lines.join('\n'))
+  },
+
   async help () { say(HELP) }
 }