kaloko 0.5.2 → 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'
@@ -73,12 +75,17 @@ Project
                                     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; asks "Keep a visual changelog?"
-                                    (--docs: changelog adds CHANGELOG.md and the config block, full also docs/ folders)
+                                    (--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
@@ -228,21 +235,59 @@ 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] [--dry-run] [--json]
+  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
+                                    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)
@@ -254,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]
@@ -394,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
@@ -801,7 +897,7 @@ const commands = {
       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 })}`); say(`Added the changelog settings to ${relative(cwd, cfgFile)}${products.length ? ` with ${products.length} products (${products.map((p) => p.slug).join(', ')})` : ''}`) }
+      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 })
@@ -815,7 +911,7 @@ const commands = {
           await mkdirp(dirname(f), { recursive: true })
           await writeFile(f, text)
         }
-        say('Docs folders in docs/ (tutorials, how-to, reference, explanation) with an index')
+        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'
@@ -920,7 +1016,7 @@ 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)
     // 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)
@@ -1390,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
@@ -1568,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 }
@@ -1663,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 {}
@@ -1680,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)
@@ -1781,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(() => ({}))
@@ -2039,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).')
@@ -2095,6 +2258,37 @@ const commands = {
     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)
@@ -2103,6 +2297,14 @@ const commands = {
     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})` : ''}`]
@@ -2111,6 +2313,7 @@ const commands = {
       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'))

package/src/lib/changelog.mjs

@@ -259,7 +259,7 @@ export async function releaseProduct ({ root, config, product, version = null, d
   const tag = tagFor(src.pattern, v)
   const commit = (await tagExists(root, tag)) ? ((await out('git', ['rev-list', '-n', '1', tag], root)) || '').trim() : ((await out('git', ['rev-parse', 'HEAD'], root)) || '').trim()
   const payload = {
-    product: { slug: product.slug, name: product.name, projects: product.projects, modules: product.modules, reference_env: product.reference_env, default_scenario: product.default_scenario, implicit: product.implicit, version_source: { source: src.source, ...(src.path ? { path: src.path } : {}), pattern: src.pattern, ...(src.tool ? { tool: src.tool } : {}) }, ...(product.publish ? { publish: product.publish } : {}), ...(await repoUrl(root)) },
+    product: await productPayload(root, product, src),
     release: { product: product.slug, version: v, date: section?.date || day, changelog: md, source_hash: sha256(md), tag: (await tagExists(root, tag)) ? tag : null, commit: /^[0-9a-f]{40}$/.test(commit) ? commit : null, ...(runs ? { runs } : {}) }
   }
   if (dryRun) return { version: v, date: payload.release.date, file, section: !!section, finalized, source: src, notes, payload, items: parseEntry(md).groups.reduce((n, g) => n + g.items.length, 0), refs: refs.length }
@@ -268,6 +268,11 @@ export async function releaseProduct ({ root, config, product, version = null, d
   const rec = await client.request('POST', `/orgs/${config.org}/releases`, payload.release)
   return { version: v, date: payload.release.date, file, section: !!section, finalized, source: src, notes, release: rec, product: saved.product, items: parseEntry(md).groups.reduce((n, g) => n + g.items.length, 0), refs: refs.length }
 }
+/** The product as the service records it (POST /products): from the config, with the version source found. */
+export async function productPayload (root, product, src) {
+  return { slug: product.slug, name: product.name, projects: product.projects, modules: product.modules, reference_env: product.reference_env, default_scenario: product.default_scenario, implicit: product.implicit, version_source: { source: src.source, ...(src.path ? { path: src.path } : {}), pattern: src.pattern, ...(src.tool ? { tool: src.tool } : {}) }, ...(product.publish ? { publish: product.publish } : {}), ...(await repoUrl(root)) }
+}
+
 async function repoUrl (root) {
   const r = await repoSlug(root)
   return r?.host === 'github' ? { repo: `https://github.com/${r.slug}` } : r?.host === 'gitlab' ? { repo: `https://gitlab.com/${r.slug}` } : {}
@@ -276,8 +281,9 @@ async function repoUrl (root) {
 // ---------- init and doctor ----------
 
 /** The config block `kaloko init --docs=changelog|full` adds (comments say what each line does). */
-export function docsConfigBlock ({ products = null } = {}) {
+export function docsConfigBlock ({ products = null, full = false } = {}) {
   const lines = ['', '# Visual changelog: kaloko changelog draft writes the Unreleased entry with step references,', '# kaloko release <version> records the release and its pictures (docs/DOCS-CHANGELOG.md on kaloko.app)', 'docs:', '  changelog: CHANGELOG.md', '  version_source: auto       # git-tag | package.json | release-please | changesets | semantic-release']
+  if (full) lines.push('  dir: docs                  # guides with step references; kaloko docs publish sends them, kaloko docs check checks them', '  # languages: [en, cs]      # the first is the originals\' language; translations sit next to them (guide.cs.md)')
   if (products?.length) {
     lines.push('# one product per app in this repository; scenarios say which one they show (product: <slug>)', 'products:')
     for (const p of products) lines.push(`  ${p.slug}:`, `    name: ${JSON.stringify(p.name)}`, `    version: { source: package.json, path: ${p.path} }`, `    docs: { changelog: ${p.dir}/CHANGELOG.md }`)
@@ -298,13 +304,73 @@ export async function detectProducts (root) {
   return out.length > 1 ? out : []
 }
 
-/** Diátaxis folders and an index for `kaloko init --docs=full` (only what is missing). */
+/**
+ * Diátaxis folders and an index for `kaloko init --docs=full` (only what is missing). Each folder's README says what
+ * belongs there and carries a template in a comment (comments never show on Kaloko or in exports).
+ */
 export const DOCS_SKELETON = {
-  'docs/index.md': '# Documentation\n\nGuides for the people who use the product. Pictures are step references\n(`![](kaloko:<scenario>/<step>)`) that always show the newest accepted screen.\n\n- [Tutorials](tutorials/) — learn by doing, start to finish\n- [How-to guides](how-to/) — one task each\n- [Reference](reference/) — the facts to look up\n- [Explanation](explanation/) — why it works this way\n',
-  'docs/tutorials/README.md': '# Tutorials\n',
-  'docs/how-to/README.md': '# How-to guides\n',
-  'docs/reference/README.md': '# Reference\n',
-  'docs/explanation/README.md': '# Explanation\n'
+  'docs/index.md': '# Documentation\n\nGuides for the people who use the product. Pictures are step references\n(`![](kaloko:<scenario>/<step>)`) that always show the newest accepted screen.\n\n- [Tutorials](tutorials/README.md): learn by doing, start to finish\n- [How-to guides](how-to/README.md): one task each\n- [Reference](reference/README.md): the facts to look up\n- [Explanation](explanation/README.md): why it works this way\n',
+  'docs/tutorials/README.md': `# Tutorials
+
+A tutorial takes a newcomer through a first success, start to finish, on a path that always works.
+
+<!-- Template (copy into a new file, e.g. first-order.md):
+---
+title: Your first order
+order: 1
+---
+# Your first order
+
+In ten minutes you will have placed an order and seen it in your account.
+
+1. Open the shop and put a tea in the cart.
+   ![Cart](kaloko:checkout/cart)
+2. Choose **Checkout** and pay with a test card.
+   ![Payment](kaloko:checkout/payment)
+
+You have placed your first order. Next: [track it](../how-to/track-an-order.md).
+-->
+`,
+  'docs/how-to/README.md': `# How-to guides
+
+One task per page, for someone who already knows what they want to do.
+
+<!-- Template (copy into a new file, e.g. pay-with-apple-pay.md):
+# Pay with Apple Pay
+
+1. Open the cart and choose **Checkout**.
+   ![Cart](kaloko:checkout/cart)
+2. Choose **Apple Pay** above the card form and confirm on your phone or Mac.
+   ![Payment](kaloko:checkout/payment)
+
+If the button is missing, your browser has no Apple Pay set up.
+-->
+`,
+  'docs/reference/README.md': `# Reference
+
+Facts to look up: fields, limits, settings, keyboard shortcuts. Tables and lists, no story.
+
+<!-- Template (copy into a new file, e.g. order-states.md):
+# Order states
+
+| State | What it means |
+|---|---|
+| Paid | The payment went through; the order waits for packing. |
+| Shipped | The parcel left the warehouse. |
+
+![Order detail](kaloko:account/order-detail)
+-->
+`,
+  'docs/explanation/README.md': `# Explanation
+
+Why things work the way they do: background, choices, trade-offs.
+
+<!-- Template (copy into a new file, e.g. why-we-hold-payments.md):
+# Why a payment waits a day
+
+Card payments are confirmed the next morning, so a cancelled order costs the customer nothing.
+-->
+`
 }
 
 /**

package/src/lib/ci.mjs

@@ -209,3 +209,74 @@ export function addPreviewEnvironment (text, name = 'preview') {
   const at = m.index + m[0].length
   return text.slice(0, at) + '\n' + block + text.slice(at)
 }
+
+// ---------- releases (docs/DOCS-CHANGELOG.md → release-tool integrations) ----------
+
+const TOOL_SNIPPETS = {
+  'release-please': { after: 'googleapis/release-please-action (id: release)', when: '${{ steps.release.outputs.release_created }}', version: '${{ steps.release.outputs.version }}' },
+  changesets: { after: 'changesets/action (id: changesets)', when: "${{ steps.changesets.outputs.published == 'true' }}", version: '' },
+  'semantic-release': { after: 'npx semantic-release', when: null, version: '' }
+}
+
+/**
+ * .github/workflows/kaloko-release.yml: when a GitHub release is published (release-please, semantic-release with
+ * @semantic-release/github and changesets all publish one) or by hand, `kaloko release <version> --no-write` records
+ * it on Kaloko: the entry the release tool wrote, the accepted runs that are its pictures, and the docs of that
+ * version. `products`: [{ slug, pattern }] (tag patterns such as v* or shop-v*); several products get one step each.
+ */
+export function releaseWorkflow ({ products = [{ slug: null, pattern: 'v*' }], pm = 'npm', dependency = true, version = 'latest', node = 22, tool = null }) {
+  const { install, kaloko: k } = runner({ pm, dependency, version })
+  const several = products.length > 1
+  const steps = products.map((p) => {
+    const prefix = String(p.pattern || 'v*').split('*')[0]
+    const flag = several || p.slug ? ` --product ${q(p.slug)}` : ''
+    return `      - name: Record ${p.slug || 'the release'} on Kaloko
+${several ? `        if: startsWith(env.TAG, '${prefix}')\n` : ''}        run: ${k} release "\${TAG#${prefix}}"${flag} --no-write`
+  }).join('\n')
+  return `# Kaloko: record every release on Kaloko once your release tool has published it: its changelog entry with
+# before/after pictures, the accepted runs that are its reference, and the docs of that version.
+# Written by kaloko ci github --release${tool ? ` (${tool} found)` : ''}. Secret: KALOKO_TOKEN (tester role, upload scope).
+# kaloko release --no-write only reads CHANGELOG.md; the release tool keeps writing it.
+name: Kaloko release
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Tag of the release to record (e.g. v2.4.0)
+        required: true
+permissions:
+  contents: read
+jobs:
+  record:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      KALOKO_TOKEN: \${{ secrets.KALOKO_TOKEN }}
+      GH_TOKEN: \${{ github.token }}
+      KALOKO_AGENT: github-actions
+      TAG: \${{ github.event.release.tag_name || inputs.tag }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: \${{ github.event.release.tag_name || inputs.tag }}
+          fetch-depth: 0   # the tags and the history since the previous release
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${node}
+${install ? `${['pnpm', 'yarn'].includes(pm) ? '      - run: corepack enable\n' : ''}      - run: ${install}\n` : ''}${steps}
+`
+}
+
+/** The step to paste into an existing release workflow, right after the release tool's own step. */
+export function releaseSnippet ({ tool = null, pm = 'npm', dependency = true, version = 'latest', product = null }) {
+  const { kaloko: k } = runner({ pm, dependency, version })
+  const s = TOOL_SNIPPETS[tool] || { after: 'the step that publishes the release', when: null, version: '' }
+  return `# after ${s.after}:
+      - name: Record the release on Kaloko
+${s.when ? `        if: ${s.when}\n` : ''}        run: ${k} release${s.version ? ` ${s.version}` : ''}${product ? ` --product ${q(product)}` : ''} --no-write
+        env:
+          KALOKO_TOKEN: \${{ secrets.KALOKO_TOKEN }}
+`
+}

package/src/lib/design-cli.mjs

@@ -297,11 +297,31 @@ export async function syncDesign ({ config, root, run, scenario, env, client, ar
   return { pushed: toPush.length, pulled: toPull.length, conflicts: conflicts.length ? conflicts : null, seq: after.seq }
 }
 
-/** Publishes the draft head as a version (a run of the design environment). */
+/** The notes an agent or person wrote for a version: --notes <file> or --notes - (stdin); null without the option. */
+export async function readNotesArg (value, stdin = process.stdin) {
+  if (value == null || value === false) return null
+  if (value === true) throw new UserError('--notes takes a file (Markdown, text or JSON) or - for standard input.')
+  if (value === '-') { const chunks = []; for await (const c of stdin) chunks.push(c); return Buffer.concat(chunks.map((c) => Buffer.from(c))).toString('utf8') }
+  try { return await readFile(value, 'utf8') } catch { throw new UserError(`--notes: cannot read ${value}.`) }
+}
+
+/** What publishing the draft now would write as "what changed" (kaloko share --notes-preview). */
+export async function previewNotes ({ config, scenario, client, args, say }) {
+  const branch = typeof args.branch === 'string' ? args.branch : 'main'
+  const r = await client.request('GET', `/orgs/${config.org}/scenarios/${enc(scenario.id)}/versions/draft/notes?branch=${enc(branch)}`)
+  if (args.json) { say(JSON.stringify(r, null, 2)); return r }
+  const { notesText } = await import('./design-notes.mjs')
+  say(`What publishing now would say (${r.changed} changed, ${r.unchanged} unchanged${r.notes?.from ? ` since v${r.notes.from.version}` : ''}):\n\n${notesText(r.notes, { lang: args.lang === 'cs' ? 'cs' : 'en' })}\n\nWrite your own in a file (a summary, then "step-id: what changed" lines) and publish with kaloko share --notes <file>.`)
+  return r
+}
+
+/** Publishes the draft head as a version (a run of the design environment), with "what changed" notes. */
 export async function publishVersion ({ config, scenario, client, args, say }) {
   const branch = typeof args.branch === 'string' ? args.branch : 'main'
-  const r = await client.request('POST', `/orgs/${config.org}/scenarios/${enc(scenario.id)}/versions`, { branch, ...(typeof args.name === 'string' ? { name: args.name } : {}) })
+  const notes = await readNotesArg(args.notes)
+  const r = await client.request('POST', `/orgs/${config.org}/scenarios/${enc(scenario.id)}/versions`, { branch, ...(typeof args.name === 'string' ? { name: args.name } : {}), ...(notes ? { notes } : {}) })
   say(`Version v${r.version}${r.name ? ` "${r.name}"` : ''} · ${r.changed} changed, ${r.unchanged} unchanged${r.changed_steps.length ? ` (${r.changed_steps.join(', ')})` : ''}\n${r.url}`)
+  if (r.notes) { const { notesText } = await import('./design-notes.mjs'); say(`\nWhat changed${notes ? ' (your notes over the generated ones)' : ''}:\n${notesText(r.notes)}`) }
   return r
 }