kaloko 0.5.2 → 0.7.0

package/skills/kaloko/reference/integrations.md

@@ -0,0 +1,67 @@
+# Jira, Linear, channels and hosted runs
+
+What the organization connected on kaloko.app (Settings → Integrations, done by an
+admin) and what you may do with it from the CLI and MCP.
+
+## Issues in Jira or Linear
+
+When a reviewer returned a step or a criterion fails and the team tracks work in
+Jira or Linear, file it there from the step instead of copying text by hand:
+
+```bash
+kaloko issue create --step checkout --to jira --criterion AC2 --note "Total ignores the voucher"
+kaloko issue list --state open
+```
+
+- `--run <id>` names the shared run; without it the current run is used once it
+  is shared. MCP: `create_issue`, `list_issues`.
+- The issue gets the screenshot, the criterion with its evidence, the reviewers'
+  open notes on the step and a link back to the step. The project or team comes
+  from the admin's mapping per Kaloko project; `--target WEB` overrides it.
+- The returned note on the step (or a new comment) mirrors the issue: when the
+  issue is done or cancelled in the tracker, the thread gets a reply and is
+  resolved; reopened, it opens again. Do not resolve that thread yourself.
+- Needs the Developer / Tester role and a token with the comment scope. A 409
+  means the tracker is not connected or the project has no mapping: tell the
+  person, an admin sets it up.
+- Name the issue key in the branch (`feat/WEB-12-gift-cards`, Linear's
+  `anna/eng-42-…`) or the pull request title, or `issue: { key: WEB-12 }` in the
+  scenario: the run links to the issue and the issue gets a comment with the run.
+
+Ask before filing issues in bulk; one issue per real problem, not per criterion.
+
+## Channels per project
+
+Slack and Teams channels are chosen per project by an admin, with the events
+each wants (new run, returned, accepted, comment, mention, release recorded) and
+quiet hours. Nothing to do from the CLI: sharing, returning and recording a
+release reach the right channels. Restricted projects reach only channels that
+name them.
+
+## Hosted runs
+
+Kaloko can open a read-only scenario's pages on its own browsers every day or
+week and share the run like yours (Business plan, a monthly page budget):
+
+```bash
+kaloko schedule add --scenario qa/flows/public.yml --env production --every day --at 5
+kaloko schedule add --scenario qa/flows/account.yml --env staging --every week --weekday mon --account anna
+kaloko schedule list            # next and last run, pages used this month
+kaloko schedule run <id>        # starts within 15 minutes
+kaloko schedule pause|resume|remove <id>
+```
+
+- Works for: public pages, pages behind HTTP Basic (the environment's
+  `access.basic` variables are sent once and stored encrypted), and signed-in
+  pages through a session saved with `kaloko auth save` (`--account`, cookies only).
+- Opens only steps whose script just opens the page (`steps/open.mjs`, or a
+  script that only calls `page.goto`). Steps that click or type are left out and
+  named in the answer. Criteria decided: `exists`, `absent`, `count`, `text_*`,
+  `attr_*`, `title_matches`, `meta_matches`; the rest shows "not evaluated".
+- Does not work for: native apps, local or private addresses (localhost, IPs,
+  `.local`), header credentials, base URLs per locale.
+- For those, or for the full walk on a schedule, write a GitHub Actions
+  workflow instead: `kaloko schedule export github --scenario <file> --env <name>
+  [--every week] [--at 5]`. It names the repository secrets it needs.
+- A 404 from `schedule add` means hosted runs are not enabled on this service:
+  use the workflow.

package/skills/kaloko/reference/mcp.md

@@ -33,12 +33,14 @@ file.
 | `decide_step` | records your (the agent's) decision on a step: `approve`, or `return` with a `note`; marked as an agent's and not counted as a person's. Never use it to approve for a person |
 | `revoke_carried_approval` | revokes an approval carried over to a step that looks unchanged but should be looked at again (`run_id`, `step`) |
 | `get_step_assets` | documentation layer (Business): newest capture of every step of a scenario with stable image, HTML and metadata URLs (`scenario`, `step`, `locale`, `viewport`, `accepted`) |
+| `list_products` | the products the caller reads: name, modules, the projects it maps that the caller sees, the newest release, published docs (versions, languages), who reads it (and the public link), whether the caller manages it, links to its page, changelog and docs |
 | `get_changelog` | the visual changelog of a product (`product`, `version`, `resolve: true` for the pictures, `limit`): releases newest first with the entry as written and its groups; see [docs.md](docs.md) |
 | `draft_changelog_entry` | what accepted runs since the last release (or `since`) show differently, as a Keep a Changelog draft with before/after step references (`product`, `since`) |
 | `resolve_step_image` | one step reference (`ref` = `kaloko:<scenario>/<step>?…`, `product`, `version`, `locale`, `viewport`) as a signed image URL with its run, how the version was found and canvas links |
 | `list_step_changes` | documentation layer: steps whose capture or status changed since the previous accepted run or `since` (`scenario`, `since`, `accepted`); see [documentation.md](documentation.md) |
 | `get_started` | where the organization stands (`empty`, `sample`, `active`), its sample run, the next steps and a prompt; call it in a new project, see [first-run.md](first-run.md) |
 | `add_sample_run` | adds the sample run (or returns the one there is); needs an upload or full token and the Developer / Tester role |
+| `search_screens` | the screen library: newest screenshot of every step across the organization's flows (`q` words matched against titles, ids, paths, URLs, page title and H1; `project`, `product`, `module`, `scenario`, `locale`, `viewport`, `device`, `status`, `environment`; `source: design` or `all` for design versions; `group: none` for every locale and viewport; `cursor` from `next`), each with a signed image and the canvas link |
 | `get_affected_steps` | which steps of a scenario changed files reach, with the reason per step (`scenario`, `changed_files`, `run_id`, `upstream`); route files are matched against the step paths and URLs of the newest run. Imports and `affects:` globs need the repository: `kaloko affected` follows them |
 
 ## Comment tools
@@ -52,6 +54,9 @@ file.
 | `get_signoff_record` | the signed acceptance record of an accepted run (Business): approvals with provenance, criteria, capture hashes, signature |
 | `resolve_comment` | close a thread with a `note` that says what changed (it becomes the last reply) |
 | `reopen_comment`, `edit_comment`, `delete_comment` | reopen; edit or delete your own comment |
+| `create_issue` | a Jira or Linear issue from a step (`run_id`, `step`, `to`: jira or linear, optional `criterion`, `title`, `note`, `locale`, `viewport`, `target`): screenshot, criterion, notes and a link back; the step's thread resolves when the issue is done. Developer / Tester, scope comment; see [integrations.md](integrations.md) |
+| `list_issues` | issues created from steps with key, URL and state (`run_id`, `scenario`, `state`) |
+| `list_schedules`, `run_schedule` | hosted runs: schedules of read-only scenarios on Kaloko's browsers with the month's page budget; start one now (`id`) |
 
 Writes need a token with scope full. Follow *Processing feedback* in
 [collaboration.md](collaboration.md).
@@ -79,6 +84,8 @@ The same data and permissions as the REST API; each tool is its REST route.
 | `list_step_changes` | steps that differ between two references (default design reference → draft) |
 | `get_references`, `get_tokens` | design reference and baseline; the project's token set |
 | `get_draft_feedback` | draft comments, pinned ones with their element |
-| `publish_version`, `set_reference`, `set_step_status`, `add_draft_comment` | writes: need a token with scope full; ask first where the skill says so |
+| `get_version_notes` | what changed in a version (`version`: vN or run id) or what publishing the draft now would say (`version: draft`): a summary and one plain sentence per changed step; text by default, `format: json` for the structure |
+| `publish_version`, `set_reference`, `set_step_status`, `add_draft_comment` | writes: need a token with scope full; ask first where the skill says so. `publish_version` takes `notes` (a summary, then `step-id: text` lines, or `{ summary, steps }`) |
+| `set_version_notes` | rewrite the summary or step texts of a published version's notes (design scope) |
 
 Files are not uploaded over MCP: the CLI (`kaloko sync`) or the REST blob endpoints carry them.

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,68 @@ 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
+
+Products (products: in kaloko.config.yml; without it the project is the product)
+  products sync [--product p] [--dry-run] [--json]
+                                    Put the products of the config on Kaloko: name, projects, modules, version
+                                    source, reference environment and default scenario, without recording a
+                                    release. They show under Products in the app with their changelog and docs;
+                                    publish: is applied only for an admin of the product's projects
+  products list [--json]            The products on Kaloko you read: newest release, docs, who reads them, and
+                                    the products of the config that are not on Kaloko yet
+
 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 +308,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 +456,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 +906,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 +920,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'
@@ -874,7 +979,7 @@ const commands = {
     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, loggedIn: !!process.env.KALOKO_TOKEN, devServer: detected && !running ? detected : null, scenario: first && relative(cwd, first) }).join('\n'))
+    say(initNextSteps({ base, org, loggedIn: !!process.env.KALOKO_TOKEN, devServer: detected && !running ? detected : null, scenario: first && relative(cwd, first), products: /^products:/m.test(written) }).join('\n'))
     say(`Scenario template: ${join(packageRoot, 'templates', 'scenario.yml')}`)
   },
 
@@ -920,7 +1025,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 +1495,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 +1697,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 +1793,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 +1811,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 +1918,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 +2190,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 +2267,55 @@ 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 products sync|list`: the products of the config on Kaloko, without a release; what the service has. */
+  async products (args) {
+    const sub = args._[0]
+    if (!['sync', 'list'].includes(sub)) throw new UserError('Usage: kaloko products sync [--product p] [--dry-run] [--json]\n       kaloko products list [--json]')
+    const { config, root } = await context(args)
+    const lib = await import('./lib/changelog.mjs')
+    if (sub === 'list') {
+      if (!config.org) throw new UserError('Set org: in the config first.')
+      const r = await lib.listProducts({ root, config, client: service(config) })
+      say(args.json ? JSON.stringify(r, null, 2) : lib.formatList(r))
+      return
+    }
+    if (!config.org && !args['dry-run']) throw new UserError('Set org: in the config first.')
+    const r = await lib.syncProducts({ root, config, client: args['dry-run'] ? null : service(config), only: typeof args.product === 'string' ? args.product : null, dryRun: !!args['dry-run'] })
+    say(args.json ? JSON.stringify(r, null, 2) : lib.formatSync(r))
+    if (r.products.some((p) => p.ok === false)) process.exitCode = 1
+  },
+
   /** `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 +2324,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 +2340,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'))