kaloko 0.5.1 → 0.5.2

package/README.md

@@ -210,6 +210,34 @@ link) and reads names from the accessibility tree. Pixel diffs skip the
 regions a step ignores; `kaloko walk --stability 3` and `kaloko stability`
 find the clocks, ads and carousels worth ignoring.
 
+## A changelog with pictures
+
+Your accepted runs already hold every screen of the release. `CHANGELOG.md`
+can show them: a picture names a step instead of a file, and Kaloko shows the
+accepted capture of it.
+
+```markdown
+- You can pay with Apple Pay in the checkout.
+  ![before](kaloko:checkout/payment?version=prev) ![after](kaloko:checkout/payment)
+```
+
+```bash
+npx kaloko changelog draft            # the Unreleased entry: merged PRs and changed screens, before and after
+npx kaloko changelog draft --apply    # the same, written into CHANGELOG.md (Keep a Changelog)
+npx kaloko release 2.4.0              # record the release and its pictures; prints the changelog page
+```
+
+The draft groups pull requests and commits (Conventional Commits when you
+use them) into Added, Changed, Fixed and Removed; your agent rewrites the
+lines for people. The version comes from what the repository already uses
+(git tags, `package.json`, release-please, changesets, semantic-release);
+when a release tool owns `CHANGELOG.md`, Kaloko only reads it. The page on
+kaloko.app has a slider between before and after, switches language and
+screen size, and links each picture to its flow on the canvas. Share it with
+guests, readers from your company's domain, or publish it with a feed.
+Repositories with several apps list them under `products:` in
+`kaloko.config.yml`.
+
 ## Design (Kaloko Design)
 
 Design the screens of a flow as live HTML with your own agent and skills, in the same scenario that development

package/package.json

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

package/schemas/config.v1.json

@@ -9,6 +9,13 @@
     "schema": { "const": "qawalk.config.v1" },
     "org": { "type": "string", "description": "Organization slug on kaloko.app." },
     "project": { "type": "string" },
+    "products": {
+      "type": "object",
+      "description": "Optional: what is released and versioned as a whole and has its own visual changelog (docs/DOCS-CHANGELOG.md). Without it the project is the product. Keys are product slugs.",
+      "propertyNames": { "pattern": "^[a-z0-9][a-z0-9._-]{0,79}$" },
+      "additionalProperties": { "$ref": "#/$defs/product" }
+    },
+    "docs": { "$ref": "#/$defs/docs" },
     "scenarios": { "type": "array", "items": { "type": "string" }, "description": "Glob patterns of scenario files." },
     "output": { "type": "string", "description": "Run folder; default tmp/kaloko (tmp/qawalk when only that one exists)" },
     "browser": {
@@ -106,6 +113,45 @@
     }
   },
   "$defs": {
+    "product": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "name": { "oneOf": [{ "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" }, "description": "Name per language, e.g. { en: Web shop, cs: E-shop }." }] },
+        "version": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Where the product's version comes from. Default: detected (release-please, changesets, semantic-release, package.json, pyproject.toml, Cargo.toml, else git tags v*).",
+          "properties": {
+            "source": { "enum": ["auto", "git-tag", "package.json", "release-please", "changesets", "semantic-release", "pyproject", "cargo", "gemspec", "manual"] },
+            "path": { "type": "string", "description": "File that holds the version (package.json of the app, the release-please manifest)." },
+            "pattern": { "type": "string", "description": "Git tag pattern with one *, e.g. shop-v* (default v*)." }
+          }
+        },
+        "docs": { "$ref": "#/$defs/docs" },
+        "project": { "type": "string", "description": "The Kaloko project people review this product in." },
+        "projects": { "type": "array", "items": { "type": "string" }, "description": "Several projects that work on this product." },
+        "modules": { "type": "array", "items": { "type": "string" } },
+        "reference_env": { "type": "string", "description": "Environment whose accepted runs the pictures come from (default: any)." },
+        "default_scenario": { "type": "string", "description": "Scenario of short step references (kaloko:<step>)." },
+        "publish": { "enum": ["members", "domain", "public"], "description": "Who reads the changelog on Kaloko; domain and public need an admin on the service." }
+      }
+    },
+    "docs": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Visual changelog and docs settings (all optional).",
+      "properties": {
+        "dir": { "type": "string", "description": "Docs sources (default docs)." },
+        "changelog": { "type": "string", "description": "Changelog file (default CHANGELOG.md)." },
+        "style": { "enum": ["keep-a-changelog", "release-notes"] },
+        "version_source": { "enum": ["auto", "git-tag", "package.json", "release-please", "changesets", "semantic-release", "pyproject", "cargo", "gemspec", "manual"] },
+        "languages": { "type": "array", "items": { "type": "string" } },
+        "framework": { "enum": ["auto", "docusaurus", "vitepress", "mkdocs", "nextra", "plain"] },
+        "publish": { "enum": ["members", "domain", "public"], "description": "Who reads the changelog on Kaloko; domain and public need an admin on the service." },
+        "images": { "type": "object", "additionalProperties": false, "properties": { "viewport": { "type": "string" }, "locale": { "type": "string", "description": "reader (the reader's language) or a locale." } } }
+      }
+    },
     "record": {
       "description": "Recordings of walked steps (opt-in): true or step records each step from the previous screen to its capture; flow records the whole walk per locale with a chapter per step; failed keeps only steps that fail; false or off turns it off. Uploaded on Business and Enterprise.",
       "oneOf": [

package/schemas/run.v1.json

@@ -58,6 +58,14 @@
         },
         "archived": {
           "type": "boolean"
+        },
+        "product": {
+          "type": ["string", "null"],
+          "description": "Product the flow documents (scenario product tag, or the only product of the config)."
+        },
+        "module": {
+          "type": ["string", "null"],
+          "description": "Module of the product (scenario module tag)."
         }
       }
     },

package/schemas/scenario.v1.json

@@ -166,6 +166,14 @@
       "$ref": "#/$defs/slug",
       "description": "Optional project this flow belongs to; overrides `project` from kaloko.config.yml and the repository name for its runs."
     },
+    "product": {
+      "$ref": "#/$defs/slug",
+      "description": "Product this flow documents (a key of `products:` in kaloko.config.yml). The visual changelog and docs of that product use its steps; with one product in the config, untagged flows belong to it."
+    },
+    "module": {
+      "$ref": "#/$defs/slug",
+      "description": "Module of the product (one of its `modules:`), for changelog and docs sections per module."
+    },
     "capture": {
       "$ref": "#/$defs/capture"
     }

package/skills/kaloko/SKILL.md

@@ -16,7 +16,9 @@ description: >
   reference, checking implementation against it), and when implementing a
   screen that has an approved design (read the step spec, build with its
   tokens, check drift), and when a step should be recorded on video or its
-  trace read (actions, requests, console).
+  trace read (actions, requests, console), and when a user-visible change
+  should land in the visual changelog (CHANGELOG.md with step references,
+  kaloko changelog draft, kaloko release) or a guide should show a step.
 ---
 
 # Kaloko
@@ -37,6 +39,11 @@ the canvas, storage and collaboration are the service.
   for them (`kaloko share` prints it; `kaloko review` repeats it), and you
   read `kaloko feedback` and `kaloko inbox` before continuing on that task.
 - Changes to intent are written back to `ACCEPTANCE.md` (change log row).
+- When the project keeps a visual changelog (`CHANGELOG.md`, `docs:` or
+  `products:` in the config) and the change is user-visible: the Unreleased
+  entry says it for people, with step references for the screens it changed
+  (`kaloko changelog draft`), and new scenarios carry `product:` (and
+  `module:`) when the config has products.
 - When you implemented a step from an approved design: you read its spec
   (`kaloko spec <step>`), walked the implementation with `packs: [design]`,
   and `kaloko drift` is clean or the PR names each difference left for a
@@ -61,6 +68,8 @@ the design folder, walk, and sync the draft (including taking others' steps
 with `--theirs`). Move to the trash runs you uploaded in this session that
 were superseded before anyone looked at them (debug rounds: no comments, no
 verdict), and run `kaloko prune` without `--yes` to see what a clean-up would do.
+Draft and edit the Unreleased section of the changelog (`kaloko changelog draft
+--apply`) and add step references to it and to guides.
 
 ## Ask first
 
@@ -70,7 +79,8 @@ replacing a CI workflow (`kaloko ci github|gitlab`), uploading with
 design reference or baseline, merging a design branch, keeping your version of
 a step in a sync conflict (`--mine`), turning on `html_view`, turning on recordings for
 a whole project (`capture.record` in the config: storage), a real clean-up
-(`kaloko prune --yes`), trashing someone else's run, archiving a scenario, and
+(`kaloko prune --yes`), trashing someone else's run, archiving a scenario,
+recording a release (`kaloko release`) or asking to publish a changelog, and
 anything the environment profile blocks. Never trash an accepted run, a
 baseline, a run with review comments, or a run linked from an open PR or issue
 comment. Never approve a
@@ -120,6 +130,10 @@ they can do; never write secrets into the config, a scenario or a script.
   [reference/collaboration.md](reference/collaboration.md)
 - Reading runs, feedback and the inbox over MCP instead of the CLI:
   [reference/mcp.md](reference/mcp.md)
+- The visual changelog and guides with step references (`kaloko:<scenario>/<step>`):
+  drafting the Unreleased entry, templates for entries, client release notes and
+  how-tos, products, modules and versions, who reads it:
+  [reference/docs.md](reference/docs.md)
 - Refreshing a manual, course or product documentation from the newest
   captures (latest URLs, changed steps, webhooks, export):
   [reference/documentation.md](reference/documentation.md)

package/skills/kaloko/reference/docs.md

@@ -0,0 +1,127 @@
+# Visual changelog and docs with step references
+
+The project keeps `CHANGELOG.md` (and guides in `docs/`) in the repository. You write and update them as part of
+normal work; Kaloko turns step references into pictures from accepted runs and shows the changelog as a page that
+clients, support and marketing can read.
+
+## Step references
+
+A picture in Markdown names a step instead of a PNG file:
+
+```markdown
+![Payment](kaloko:checkout/payment)                       newest accepted capture
+![Payment](kaloko:checkout/payment?version=2.4.0)         the capture of release 2.4.0
+![Payment](kaloko:checkout/payment?version=prev)          the release before the one this entry belongs to
+![Payment](kaloko:checkout/payment?locale=cs&viewport=mobile&state=dark)
+![Payment](kaloko:payment)                                a step of the product's default_scenario
+```
+
+`<scenario>` is the scenario id, `<step>` the node id. Without `locale` and `viewport` the reader's language and
+the product's default screen are used. `state` picks a capture variant (`dark`, `webkit`, `reduce`: the values in
+capture keys like `mobile.webkit.dark`). Check a reference with MCP `resolve_step_image` or
+`GET /api/v1/orgs/<org>/steps/resolve?ref=…`: it answers the signed image URL, the run and how the version was found
+(`release`, `app_version`, `reference_env`, `accepted`; `exact: false` means a fallback).
+
+Never invent a step id or a version. Use ids from the scenario files and versions from `CHANGELOG.md` or git tags.
+
+## After a user-visible change
+
+1. Walk the affected steps and share the run as usual; a person accepts it on the canvas.
+2. `kaloko changelog draft` prints the Unreleased entry: merged pull requests and commits since the last release,
+   grouped Added / Changed / Fixed / Removed, plus before/after pictures of the screens that accepted runs show
+   differently (it needs a token for the pictures). `--apply` writes it into `CHANGELOG.md`.
+3. Edit the draft for people: what they can do now or what looks different, one change per line, no commit jargon.
+   Delete internal items (refactors, tests, CI). Keep the step references; move a picture under the line it shows.
+   Remove the `<!-- … -->` hints.
+4. Commit `CHANGELOG.md` with the change. At release time `kaloko release <version>` (ask first: it records the
+   release on Kaloko) turns Unreleased into the version, records its pictures and prints the changelog page.
+
+`--since v2.3.0` drafts from another tag; `--product shop` picks a product when the config has several.
+
+## Templates
+
+A changelog entry (Keep a Changelog):
+
+```markdown
+## [2.4.0] - 2026-10-12
+
+### Added
+
+- You can pay with Apple Pay in the checkout. ([#412](https://github.com/acme/shop/pull/412))
+  ![Payment before](kaloko:checkout/payment?version=prev) ![Payment after](kaloko:checkout/payment)
+
+### Fixed
+
+- The cart total no longer jumps while prices load on phones.
+  ![Cart](kaloko:checkout/cart?viewport=mobile)
+```
+
+Release notes for a client (a sibling file, or the text of a release on your Git host):
+
+```markdown
+# What's new in the web shop, October
+
+Customers can pay with Apple Pay. The button sits above the card form on phones and computers.
+
+![Payment](kaloko:checkout/payment?locale=cs)
+
+Also fixed: the cart total no longer jumps on phones.
+```
+
+A how-to guide (`docs/how-to/pay-with-apple-pay.md`):
+
+```markdown
+# 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)
+```
+
+Rules: write for the person using the product; one change per line; before/after pictures for changes people see;
+no internal names, prices or numbers you cannot show.
+
+## Products, modules and versions
+
+Without `products:` in `kaloko.config.yml` the project is the product and `CHANGELOG.md` in the root is its
+changelog. Pick the pattern that fits; tag new scenarios accordingly without asking each time:
+
+1. **One app, one team**: no products. Optional `docs: { changelog: CHANGELOG.md }`.
+2. **Monorepo with several apps**: one product per app, each with its version file and changelog; every scenario
+   says `product: <slug>`.
+   ```yaml
+   products:
+     shop:
+       name: { en: Web shop, cs: E-shop }
+       version: { source: package.json, path: apps/shop/package.json }
+       docs: { changelog: apps/shop/CHANGELOG.md }
+       project: eshop
+       reference_env: staging
+     admin:
+       version: { source: git-tag, pattern: "admin-v*" }
+   ```
+3. **Agency**: a project per client, a product per client deliverable; client guests of the project read only that
+   product's changelog.
+4. **Large app with modules**: one product with `modules: [checkout, account, …]`; scenarios carry
+   `product:` and `module:`; one combined release changelog with a section per module if the team wants it.
+
+The version comes from what the repository already uses: release-please, changesets, semantic-release,
+`package.json` (or pyproject/Cargo/gemspec), else git tags `v*`. When a release tool writes `CHANGELOG.md`, Kaloko
+reads its entry and never rewrites the file; put your draft into the pull request or release notes instead.
+`reference_env` says which environment the pictures come from (default: any accepted run).
+
+`kaloko doctor` warns when a product's version cannot be read or a scenario names no product while several exist.
+
+## Readers
+
+The changelog page (`/<org>/products/<product>/changelog`, or `/<org>/projects/<project>/changelog`) is read by
+everyone who sees one of the product's projects, guests included. An admin of those projects may open it to
+readers from the organization's verified domains or publish it (`/p/<org>/<product>/changelog` with an Atom feed;
+not indexed until the organization allows it). `publish:` in the config only asks for it; an admin confirms on the
+page. Never publish without the person asking.
+
+## MCP
+
+`get_changelog` (releases with entries; `resolve: true` adds the pictures), `draft_changelog_entry` (the service's
+half of a draft: changed screens with before/after references), `resolve_step_image` (one reference).

package/skills/kaloko/reference/mcp.md

@@ -33,6 +33,9 @@ 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`) |
+| `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 |

package/src/cli.mjs

@@ -69,10 +69,11 @@ 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)
   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
@@ -231,6 +232,18 @@ Results
                                     Text diff of two runs: step statuses, criterion verdicts, scores and evidence
                                     (default: current run against the scenario baseline, else the previous run)
 
+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]
+                                    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
+
 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
@@ -773,6 +786,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 })}`); 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')
+      }
+    } 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')
@@ -877,7 +922,9 @@ const commands = {
     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 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}`)
@@ -2019,12 +2066,56 @@ 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 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'] })
+    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.')
+    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) }
 }
 

package/src/lib/changelog-core.mjs

@@ -0,0 +1,323 @@
+// The visual changelog (docs/DOCS-CHANGELOG.md, phase 1), the parts the CLI and the service share: step references
+// in Markdown, Keep a Changelog parsing and editing, commit classification and the draft skeleton. No I/O here: the
+// worker imports this file too (worker/src/changelog.js), so it stays plain JavaScript without Node built-ins.
+
+// ---------- step references ----------
+
+/** Scenario and step ids as the service accepts them (design.js SCENARIO_ID). */
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,119}$/
+const PARAMS = {
+  locale: /^[A-Za-z0-9_-]{1,20}$/,
+  viewport: /^[A-Za-z0-9._-]{1,80}$/,
+  version: /^[A-Za-z0-9._+-]{1,80}$/,
+  state: /^[A-Za-z0-9._-]{1,60}$/
+}
+export const REF_SCHEME = 'kaloko:'
+
+/**
+ * A step reference `kaloko:<scenario>/<step>[?locale=&viewport=&version=&state=]`, or the short `kaloko:<step>` that
+ * means a step of the product's default scenario. `version` is a released version, `latest` (default) or `prev` (the
+ * release before the one the text belongs to); `state` picks a variant of the capture (dark, webkit, reduce: the
+ * dimension values in the capture key). Returns null for anything else.
+ */
+export function parseStepRef (ref) {
+  const s = String(ref || '').trim()
+  if (!s.startsWith(REF_SCHEME)) return null
+  const rest = s.slice(REF_SCHEME.length)
+  const qi = rest.indexOf('?')
+  const path = qi < 0 ? rest : rest.slice(0, qi)
+  let parts
+  try { parts = path.split('/').map((p) => decodeURIComponent(p)) } catch { return null }
+  if (!parts.length || parts.length > 2 || parts.some((p) => !ID.test(p))) return null
+  const out = { scenario: parts.length === 2 ? parts[0] : null, step: parts[parts.length - 1], locale: null, viewport: null, version: null, state: null }
+  const q = new URLSearchParams(qi < 0 ? '' : rest.slice(qi + 1))
+  for (const [k, v] of q) {
+    if (!(k in PARAMS)) return null
+    if (!PARAMS[k].test(v)) return null
+    out[k] = v
+  }
+  if (out.version === 'latest') out.version = null
+  return out
+}
+
+/** The reference text of a parsed (or hand-built) reference; parameters in a fixed order. */
+export function formatStepRef ({ scenario = null, step, locale = null, viewport = null, version = null, state = null }) {
+  const path = `${scenario ? `${encodeURIComponent(scenario)}/` : ''}${encodeURIComponent(step)}`
+  const q = Object.entries({ locale, viewport, version, state }).filter(([, v]) => v != null && v !== '')
+  return `${REF_SCHEME}${path}${q.length ? `?${q.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&')}` : ''}`
+}
+
+/** Every image with a step reference in a Markdown text: { alt, ref, parsed, index }; broken ones have parsed null. */
+export function findStepRefs (markdown) {
+  const out = []
+  const re = /!\[([^\]]*)\]\((kaloko:[^)\s]+)\)/g
+  let m
+  while ((m = re.exec(String(markdown || '')))) out.push({ alt: m[1], ref: m[2], parsed: parseStepRef(m[2]), index: m.index })
+  return out
+}
+
+// ---------- versions ----------
+
+/** "v2.4.0" → "2.4.0"; anything else stays as it is (trimmed). */
+export const cleanVersion = (v) => String(v ?? '').trim().replace(/^v(?=\d)/, '')
+
+/** Semantic Versioning order (prereleases before their release); versions that are not semver sort by text. */
+export function compareVersions (a, b) {
+  const p = (v) => { const m = cleanVersion(v).match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/); return m ? { n: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] || null } : null }
+  const x = p(a); const y = p(b)
+  if (!x || !y) return String(a).localeCompare(String(b))
+  for (let i = 0; i < 3; i++) if (x.n[i] !== y.n[i]) return x.n[i] - y.n[i]
+  if (x.pre === y.pre) return 0
+  if (!x.pre) return 1
+  if (!y.pre) return -1
+  return x.pre.localeCompare(y.pre, 'en', { numeric: true })
+}
+
+/** The git tag of a version for a tag pattern ("v*" → "v2.4.0", "shop-v*" → "shop-v2.4.0"). */
+export const tagFor = (pattern, version) => String(pattern || 'v*').replace('*', cleanVersion(version))
+/** The version a tag names under a pattern, or null when the tag does not match it. */
+export function versionOfTag (pattern, tag) {
+  const [pre, post = ''] = String(pattern || 'v*').split('*')
+  const t = String(tag || '')
+  if (!t.startsWith(pre) || !t.endsWith(post) || t.length <= pre.length + post.length) return null
+  return cleanVersion(t.slice(pre.length, t.length - post.length))
+}
+
+// ---------- Keep a Changelog ----------
+
+export const GROUPS = ['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security']
+const GROUP_ALIASES = { added: 'Added', new: 'Added', features: 'Added', 'minor changes': 'Added', changed: 'Changed', 'patch changes': 'Fixed', 'major changes': 'Changed', improvements: 'Changed', deprecated: 'Deprecated', removed: 'Removed', fixed: 'Fixed', 'bug fixes': 'Fixed', fixes: 'Fixed', security: 'Security', 'performance improvements': 'Changed' }
+/** A group heading as written by people or release tools ("Bug Fixes", "Minor Changes") in Keep a Changelog terms. */
+export const groupName = (h) => GROUP_ALIASES[String(h || '').trim().toLowerCase()] || String(h || '').trim()
+
+export const CHANGELOG_HEAD = `# Changelog
+
+All notable changes for the people who use this product. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow
+[Semantic Versioning](https://semver.org/). Pictures are step references
+(\`![](kaloko:<scenario>/<step>)\`) that Kaloko shows from the accepted runs.
+`
+export const CHANGELOG_SKELETON = `${CHANGELOG_HEAD}
+## [Unreleased]
+`
+
+const RELEASE_HEADING = /^##\s+(.+?)\s*$/
+const DATE = /(\d{4}-\d{2}-\d{2})/
+
+/** "## [2.4.0] - 2026-10-12", "## [1.2.0](https://…compare…) (2026-10-12)", "## 1.2.0", "## [Unreleased]". */
+export function parseHeading (line) {
+  const m = String(line).match(RELEASE_HEADING)
+  if (!m || /^#/.test(m[1])) return null
+  const text = m[1]
+  const bracket = text.match(/^\[([^\]]+)\]/)
+  const label = (bracket ? bracket[1] : text.split(/\s+/)[0]).trim()
+  if (/^unreleased$/i.test(label)) return { unreleased: true, version: null, date: null }
+  const version = cleanVersion(label)
+  if (!/^\d/.test(version)) return null
+  const rest = text.slice(bracket ? bracket[0].length : label.length)
+  return { unreleased: false, version, date: (rest.match(DATE) || [])[1] || null }
+}
+
+/** List items of a group body: each item keeps its continuation lines (pictures under it), without the "- ". */
+export function listItems (body) {
+  const items = []
+  let cur = null
+  for (const line of String(body || '').split('\n')) {
+    const m = line.match(/^[-*+]\s+(.*)$/)
+    if (m) { if (cur) items.push(cur.trimEnd()); cur = m[1]; continue }
+    if (cur != null && (/^\s+\S/.test(line) || line.trim() === '')) { cur += `\n${line.replace(/^ {1,4}/, '')}`; continue }
+    if (cur != null) { items.push(cur.trimEnd()); cur = null }
+  }
+  if (cur) items.push(cur.trimEnd())
+  return items.map((x) => x.replace(/\n+$/, '')).filter(Boolean)
+}
+
+/** Groups of a release body: [{ name, heading, items }] plus text before the first group (notes). */
+export function parseEntry (body) {
+  const groups = []; const notes = []
+  let cur = null
+  for (const line of String(body || '').replace(/\r/g, '').split('\n')) {
+    const h = line.match(/^###\s+(.+?)\s*$/)
+    if (h) { cur = { name: groupName(h[1]), heading: h[1].trim(), lines: [] }; groups.push(cur); continue }
+    if (cur) cur.lines.push(line); else notes.push(line)
+  }
+  return { notes: notes.join('\n').trim(), groups: groups.map((g) => ({ name: g.name, heading: g.heading, items: listItems(g.lines.join('\n')) })).filter((g) => g.items.length || g.name) }
+}
+
+/**
+ * A changelog file: { head (text before the first release heading), sections: [{ unreleased, version, date, heading,
+ * body, start, end }] (line numbers, end exclusive), links (the reference definitions at the bottom, by lower-case
+ * label), linksStart }.
+ */
+export function parseChangelog (text) {
+  const lines = String(text || '').replace(/\r/g, '').split('\n')
+  let linksStart = lines.length
+  while (linksStart > 0 && (/^\[[^\]]+\]:\s*\S+/.test(lines[linksStart - 1]) || lines[linksStart - 1].trim() === '')) linksStart--
+  if (!lines.slice(linksStart).some((l) => /^\[[^\]]+\]:/.test(l))) linksStart = lines.length
+  const links = {}
+  for (const l of lines.slice(linksStart)) { const m = l.match(/^\[([^\]]+)\]:\s*(\S+)/); if (m) links[m[1].toLowerCase()] = m[2] }
+  const sections = []
+  for (let i = 0; i < linksStart; i++) {
+    const h = /^##\s/.test(lines[i]) ? parseHeading(lines[i]) : null
+    if (!h) continue
+    if (sections.length) sections[sections.length - 1].end = i
+    sections.push({ ...h, heading: lines[i], start: i, end: linksStart })
+  }
+  for (const s of sections) s.body = lines.slice(s.start + 1, s.end).join('\n').trim()
+  const head = lines.slice(0, sections.length ? sections[0].start : linksStart).join('\n').trimEnd()
+  return { head, sections, links, linksStart, lines }
+}
+
+/** The section of a version (or the Unreleased one for null), or null. */
+export function sectionOf (text, version) {
+  const { sections } = parseChangelog(text)
+  const v = version == null ? null : cleanVersion(version)
+  return sections.find((s) => v == null ? s.unreleased : !s.unreleased && s.version === v) || null
+}
+
+/** The newest released version written in the file (null when none). */
+export function latestVersionIn (text) {
+  const v = parseChangelog(text).sections.filter((s) => !s.unreleased).map((s) => s.version)
+  return v.sort(compareVersions).pop() || null
+}
+
+const norm = (item) => String(item).split('\n')[0].replace(/<!--[\s\S]*?-->/g, '').replace(/\s+/g, ' ').trim().toLowerCase()
+
+/** Markdown of groups ({ Added: [items] } in Keep a Changelog order; other names after them). */
+export function groupsMarkdown (groups) {
+  const names = [...GROUPS.filter((g) => groups[g]?.length), ...Object.keys(groups).filter((g) => !GROUPS.includes(g) && groups[g]?.length)]
+  return names.map((g) => `### ${g}\n\n${groups[g].map((it) => `- ${String(it).split('\n').map((l, i) => i && l ? `  ${l}` : l).join('\n')}`).join('\n')}`).join('\n\n')
+}
+
+/**
+ * Puts draft items into the Unreleased section of a changelog: items whose first line is already there are left
+ * out, groups that exist get the new items at their end, missing groups are added in Keep a Changelog order. A file
+ * without an Unreleased section gets one above the newest release; an empty file gets the skeleton.
+ * Returns { text, added } (the number of new items).
+ */
+export function applyDraft (text, groups) {
+  let src = String(text || '')
+  if (!src.trim()) src = CHANGELOG_SKELETON
+  let parsed = parseChangelog(src)
+  let un = parsed.sections.find((s) => s.unreleased)
+  if (!un) {
+    const lines = parsed.lines
+    const at = parsed.sections.length ? parsed.sections[0].start : parsed.linksStart
+    const before = lines.slice(0, at); while (before.length && before[before.length - 1].trim() === '') before.pop()
+    src = [...before, '', '## [Unreleased]', '', ...lines.slice(at)].join('\n')
+    parsed = parseChangelog(src)
+    un = parsed.sections.find((s) => s.unreleased)
+  }
+  const existing = parseEntry(un.body)
+  const seen = new Set(parsed.sections.flatMap((s) => parseEntry(s.body).groups.flatMap((g) => g.items.map(norm))))
+  const merged = new Map(existing.groups.map((g) => [g.name, { heading: g.heading, items: [...g.items] }]))
+  let added = 0
+  for (const [name, items] of Object.entries(groups)) {
+    for (const it of items || []) {
+      if (seen.has(norm(it))) continue
+      seen.add(norm(it))
+      if (!merged.has(name)) merged.set(name, { heading: name, items: [] })
+      merged.get(name).items.push(it); added++
+    }
+  }
+  const order = [...GROUPS.filter((g) => merged.has(g)), ...[...merged.keys()].filter((g) => !GROUPS.includes(g))]
+  const body = [existing.notes, ...order.map((g) => { const x = merged.get(g); return groupsMarkdown({ [g]: x.items }).replace(/^### [^\n]+/, `### ${x.heading}`) })].filter(Boolean).join('\n\n')
+  const lines = parsed.lines
+  const out = [...lines.slice(0, un.start + 1), '', ...(body ? [body, ''] : []), ...lines.slice(un.end)]
+  return { text: out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\n*$/, '\n'), added }
+}
+
+/**
+ * Turns the Unreleased section into the release `version` of `date` and opens a new, empty Unreleased section above
+ * it. Compare links at the bottom ([unreleased]: …/compare/v1...HEAD) move along. Returns { text, changed, empty }.
+ */
+export function finalizeRelease (text, version, date, { tagPattern = 'v*' } = {}) {
+  const v = cleanVersion(version)
+  const parsed = parseChangelog(text)
+  if (parsed.sections.some((s) => !s.unreleased && s.version === v)) return { text, changed: false, empty: false }
+  const un = parsed.sections.find((s) => s.unreleased)
+  if (!un) return { text, changed: false, empty: true }
+  const lines = [...parsed.lines]
+  lines.splice(un.start, 1, '## [Unreleased]', '', `## [${v}] - ${date}`)
+  let out = lines.join('\n')
+  const link = parsed.links.unreleased
+  const m = link && link.match(/^(.*\/compare\/)(.+)\.\.\.HEAD$/)
+  if (m) {
+    const tag = tagFor(tagPattern, v)
+    out = out.replace(/^\[unreleased\]:\s*\S+$/im, `[unreleased]: ${m[1]}${tag}...HEAD\n[${v}]: ${m[1]}${m[2]}...${tag}`)
+  }
+  return { text: out, changed: true, empty: !un.body.trim() }
+}
+
+// ---------- commits and the draft ----------
+
+const CONVENTIONAL = /^(\w+)(?:\(([^)]*)\))?(!)?:\s*(.+)$/
+const INTERNAL = new Set(['docs', 'test', 'tests', 'chore', 'ci', 'build', 'style', 'refactor', 'release', 'wip', 'deps'])
+const TYPE_GROUP = { feat: 'Added', feature: 'Added', add: 'Added', fix: 'Fixed', bugfix: 'Fixed', hotfix: 'Fixed', perf: 'Changed', revert: 'Changed', remove: 'Removed', deprecate: 'Deprecated', security: 'Security', sec: 'Security' }
+
+/**
+ * Where a commit or pull request title goes: { group, text, internal, breaking, pr }. Conventional Commits when the
+ * title uses them; otherwise the first verb decides (add → Added, fix → Fixed, remove → Removed, else Changed).
+ * Documentation, tests, chores, CI, refactors, merges and releases are internal.
+ */
+export function classifyCommit (subject, body = '') {
+  let s = String(subject || '').trim()
+  let pr = null
+  const sq = s.match(/\s*\(#(\d+)\)\s*$/)
+  if (sq) { pr = Number(sq[1]); s = s.slice(0, sq.index).trim() }
+  const breaking = /BREAKING[ -]CHANGE/.test(body)
+  if (/^Merge\b|^Revert "|^v?\d+\.\d+\.\d+$|\[skip changelog\]|\[no changelog\]/i.test(s)) return { group: null, text: s, internal: true, breaking, pr }
+  const m = s.match(CONVENTIONAL)
+  if (m) {
+    const type = m[1].toLowerCase()
+    const text = sentence(m[4])
+    if (INTERNAL.has(type) && !m[3] && !breaking) return { group: null, text, internal: true, breaking: false, pr, type, scope: m[2] || null }
+    const group = TYPE_GROUP[type] || (/^(remove|drop|delete)\b/i.test(m[4]) ? 'Removed' : 'Changed')
+    return { group: m[3] || breaking ? (group === 'Added' ? 'Added' : 'Changed') : group, text, internal: false, breaking: !!m[3] || breaking, pr, type, scope: m[2] || null }
+  }
+  const verb = s.toLowerCase()
+  const group = /^(add|adds|added|new|introduce|support|allow|enable)\b/.test(verb) ? 'Added'
+    : /^(fix|fixes|fixed|correct|repair|resolve|prevent)\b/.test(verb) ? 'Fixed'
+      : /^(remove|removes|removed|drop|delete)\b/.test(verb) ? 'Removed'
+        : /^(deprecate)\b/.test(verb) ? 'Deprecated' : 'Changed'
+  return { group, text: sentence(s), internal: false, breaking, pr }
+}
+const sentence = (t) => { const x = String(t || '').trim().replace(/\.$/, ''); return x ? x[0].toUpperCase() + x.slice(1) : x }
+
+/**
+ * The draft entry: items grouped Added / Changed / Fixed / Removed (Deprecated, Security when present).
+ *
+ * commits  [{ subject, body, pr: { number, url } | null }] — merged pull requests or commits since the last release
+ * changes  [{ scenario, title, steps: [{ step, title, reason: new|changed|removed, pr: number|null }] }] — what the
+ *          accepted runs since the last release show differently (from the service)
+ * Pictures are step references: a changed step gets before and after (`?version=prev` is the previous release), a
+ * new step one picture. A step whose run came from a pull request goes under that pull request's item.
+ * Returns { groups, internal (titles left out), markdown }.
+ */
+export function draftEntry ({ commits = [], changes = [], scenarioLabel = (s) => s.title || s.scenario } = {}) {
+  const groups = {}
+  const internal = []
+  const byPr = new Map()
+  const add = (g, item) => { (groups[g] ||= []).push(item); return groups[g].length - 1 }
+  for (const c of commits) {
+    const k = classifyCommit(c.subject, c.body)
+    if (k.internal) { internal.push(c.subject); continue }
+    const number = c.pr?.number || k.pr
+    const url = c.pr?.url || null
+    const text = `${k.text}${k.breaking ? ' (breaking: say what people have to do)' : ''}${number ? ` (${url ? `[#${number}](${url})` : `#${number}`})` : ''}`
+    const i = add(k.group, text)
+    if (number && !byPr.has(number)) byPr.set(number, { group: k.group, i })
+  }
+  for (const sc of changes) {
+    for (const st of sc.steps || []) {
+      const ref = (version) => formatStepRef({ scenario: sc.scenario, step: st.step, version })
+      const title = st.title || st.step
+      const pics = st.reason === 'new' ? `![${title}](${ref(null)})` : st.reason === 'removed' ? `![${title} before](${ref('prev')})` : `![${title} before](${ref('prev')}) ![${title} after](${ref(null)})`
+      const home = st.pr && byPr.get(st.pr)
+      if (home) { groups[home.group][home.i] += `\n${pics}`; continue }
+      const g = st.reason === 'new' ? 'Added' : st.reason === 'removed' ? 'Removed' : 'Changed'
+      add(g, `**${title}** in ${scenarioLabel(sc)} <!-- say what a person notices here -->\n${pics}`)
+    }
+  }
+  return { groups, internal, markdown: groupsMarkdown(groups) }
+}

package/src/lib/changelog.mjs

@@ -0,0 +1,333 @@
+// `kaloko changelog draft` and `kaloko release` (docs/DOCS-CHANGELOG.md, phase 1): products from kaloko.config.yml,
+// the version source the repository already uses (never fighting a release tool), merged pull requests and commits
+// since the last release, the steps the accepted runs show differently (from the service), the draft entry and the
+// release record. Parsing and the draft itself are in changelog-core.mjs, shared with the service.
+import { readFile, writeFile, access, readdir } from 'node:fs/promises'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { join, resolve, relative, dirname, basename } from 'node:path'
+import { UserError, sha256 } from './util.mjs'
+import { repoSlug } from './git.mjs'
+import { cleanVersion, compareVersions, tagFor, versionOfTag, latestVersionIn, sectionOf, applyDraft, finalizeRelease, draftEntry, groupsMarkdown, parseEntry, findStepRefs, CHANGELOG_SKELETON } from './changelog-core.mjs'
+
+const run = promisify(execFile)
+async function out (cmd, args, cwd, timeout = 20000) {
+  try { return (await run(cmd, args, { cwd, timeout, maxBuffer: 50 * 1024 * 1024 })).stdout } catch { return null }
+}
+const exists = async (f) => { try { await access(f); return true } catch { return false } }
+const readJson = async (f) => { try { return JSON.parse(await readFile(f, 'utf8')) } catch { return null } }
+const readText = async (f) => { try { return await readFile(f, 'utf8') } catch { return null } }
+export const today = () => new Date().toISOString().slice(0, 10)
+
+// ---------- products ----------
+
+const slugOf = (s) => String(s || '').toLowerCase().replace(/^@[^/]+\//, '').replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80)
+
+/**
+ * Products of the configuration, normalized. Without `products:` the project is the product (implicit): its slug is
+ * the config's project, else the directory name.
+ */
+export function productsOf (config, root = process.cwd()) {
+  const docs = config.docs || {}
+  const list = Object.entries(config.products || {}).map(([slug, p]) => ({
+    slug, implicit: false, name: p.name || slug,
+    projects: [...new Set([p.project, ...(p.projects || [])].filter(Boolean))],
+    modules: p.modules || [], reference_env: p.reference_env || null, default_scenario: p.default_scenario || null,
+    version: p.version || null, docs: { ...docs, ...(p.docs || {}) }, publish: p.publish || docs.publish || null
+  }))
+  if (list.length) return list
+  const slug = slugOf(config.project || basename(root)) || 'app'
+  return [{ slug, implicit: true, name: config.project || slug, projects: [slug], modules: [], reference_env: null, default_scenario: null, version: null, docs, publish: docs.publish || null }]
+}
+
+/** The product a command works on: --product, else the only one. */
+export function pickProduct (config, root, name) {
+  const all = productsOf(config, root)
+  if (typeof name === 'string' && name) {
+    const p = all.find((x) => x.slug === name)
+    if (!p) throw new UserError(`No product ${name} in the config (${all.map((x) => x.slug).join(', ')}).`)
+    return p
+  }
+  if (all.length > 1) throw new UserError(`The config has several products; pass --product (${all.map((x) => x.slug).join(', ')}).`)
+  return all[0]
+}
+
+export const changelogFile = (root, product) => resolve(root, product.docs?.changelog || 'CHANGELOG.md')
+
+// ---------- the version source ----------
+
+const SEMREL = ['.releaserc', '.releaserc.json', '.releaserc.yml', '.releaserc.yaml', '.releaserc.js', '.releaserc.cjs', 'release.config.js', 'release.config.cjs', 'release.config.mjs']
+
+/**
+ * Where the product's version comes from, as the repository already decides it: { source, path, pattern, version,
+ * owns_changelog, tool }. The config wins (products.<p>.version or docs.version_source); otherwise release-please,
+ * changesets, semantic-release, package.json, pyproject.toml, Cargo.toml, a gemspec, else git tags (v*).
+ */
+export async function detectVersionSource (root, product = {}) {
+  const v = product.version || {}
+  const wanted = v.source && v.source !== 'auto' ? v.source : product.docs?.version_source && product.docs.version_source !== 'auto' ? product.docs.version_source : null
+  const pattern = v.pattern || 'v*'
+  const pkgPath = v.path && /package\.json$/.test(v.path) ? v.path : 'package.json'
+  const dir = v.path ? dirname(v.path) : '.'
+  const found = async (source) => {
+    if (source === 'release-please') {
+      const manifest = await readJson(join(root, '.release-please-manifest.json'))
+      const key = dir === '.' ? '.' : dir
+      return { source, path: '.release-please-manifest.json', pattern, version: manifest ? cleanVersion(manifest[key] ?? manifest['.'] ?? '') || null : null, owns_changelog: true, tool: 'release-please' }
+    }
+    if (source === 'changesets') return { source, path: pkgPath, pattern, version: cleanVersion((await readJson(join(root, pkgPath)))?.version || '') || null, owns_changelog: true, tool: 'changesets' }
+    if (source === 'semantic-release') {
+      let conf = ''
+      for (const f of SEMREL) conf += (await readText(join(root, f))) || ''
+      conf += JSON.stringify((await readJson(join(root, 'package.json')))?.release || '')
+      return { source, path: null, pattern, version: await latestTag(root, pattern), owns_changelog: conf.includes('@semantic-release/changelog'), tool: 'semantic-release' }
+    }
+    if (source === 'package.json') return { source, path: pkgPath, pattern, version: cleanVersion((await readJson(join(root, pkgPath)))?.version || '') || null, owns_changelog: false }
+    if (source === 'pyproject') { const t = await readText(join(root, v.path || 'pyproject.toml')); return { source, path: v.path || 'pyproject.toml', pattern, version: (t?.match(/^version\s*=\s*["']([^"']+)["']/m) || [])[1] || null, owns_changelog: false } }
+    if (source === 'cargo') { const t = await readText(join(root, v.path || 'Cargo.toml')); return { source, path: v.path || 'Cargo.toml', pattern, version: (t?.match(/^\[package\][\s\S]*?^version\s*=\s*"([^"]+)"/m) || [])[1] || null, owns_changelog: false } }
+    if (source === 'gemspec') {
+      const f = v.path || (await readdir(root).catch(() => [])).find((x) => x.endsWith('.gemspec'))
+      const t = f ? await readText(join(root, f)) : null
+      return { source, path: f || null, pattern, version: (t?.match(/\.version\s*=\s*["']([^"']+)["']/) || [])[1] || null, owns_changelog: false }
+    }
+    if (source === 'manual') return { source, path: null, pattern, version: null, owns_changelog: false }
+    return { source: 'git-tag', path: null, pattern, version: await latestTag(root, pattern), owns_changelog: false }
+  }
+  if (wanted) return found(wanted)
+  if (await exists(join(root, '.release-please-manifest.json')) || await exists(join(root, 'release-please-config.json'))) return found('release-please')
+  if (await exists(join(root, '.changeset', 'config.json'))) return found('changesets')
+  for (const f of SEMREL) if (await exists(join(root, f))) return found('semantic-release')
+  const pkg = await readJson(join(root, pkgPath))
+  if (pkg?.release) return found('semantic-release')
+  if (pkg?.version && !pkg.private) return found('package.json')
+  if (pkg?.version && pkg.version !== '0.0.0') return found('package.json')
+  if (await exists(join(root, 'pyproject.toml')) && /^version\s*=/m.test(await readText(join(root, 'pyproject.toml')) || '')) return found('pyproject')
+  if (await exists(join(root, 'Cargo.toml'))) return found('cargo')
+  if ((await readdir(root).catch(() => [])).some((x) => x.endsWith('.gemspec'))) return found('gemspec')
+  return found('git-tag')
+}
+
+/** The newest tag of the pattern (version order), or null. */
+async function latestTag (root, pattern) {
+  const tags = ((await out('git', ['tag', '--list', pattern], root)) || '').split('\n').map((t) => t.trim()).filter(Boolean)
+  const versions = tags.map((t) => versionOfTag(pattern, t)).filter(Boolean)
+  return versions.sort(compareVersions).pop() || null
+}
+const tagExists = async (root, tag) => !!(await out('git', ['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`], root))
+
+/**
+ * Where the draft starts: --since (a tag, or a version that has a tag), else the newest tag of the pattern reachable
+ * from HEAD, else the newest release written in the changelog when it has a tag; null = the whole history.
+ */
+export async function sinceRef (root, product, src, since, changelogText = '') {
+  const pattern = src.pattern || 'v*'
+  if (typeof since === 'string' && since) {
+    if (await tagExists(root, since)) return { ref: since, version: versionOfTag(pattern, since) || cleanVersion(since) }
+    const tag = tagFor(pattern, since)
+    if (await tagExists(root, tag)) return { ref: tag, version: cleanVersion(since) }
+    if (await out('git', ['rev-parse', '--verify', '--quiet', `${since}^{commit}`], root)) return { ref: since, version: null }
+    throw new UserError(`--since ${since}: no tag ${since} or ${tag} and no such commit.`)
+  }
+  const described = ((await out('git', ['describe', '--tags', '--abbrev=0', '--match', pattern, 'HEAD'], root)) || '').trim()
+  if (described) return { ref: described, version: versionOfTag(pattern, described) }
+  const written = latestVersionIn(changelogText)
+  if (written && await tagExists(root, tagFor(pattern, written))) return { ref: tagFor(pattern, written), version: written }
+  return { ref: null, version: written || null }
+}
+
+// ---------- pull requests and commits ----------
+
+/**
+ * Merged work since `ref` along the first-parent history: a merge of a pull request is one item (its title), other
+ * merges are opened up into their commits, plain commits are items. PR numbers come from merge subjects and squash
+ * suffixes ("(#12)"); titles and links from gh when it is there (KALOKO_NO_GH=1 skips it). `dir` limits the history
+ * to a product's folder in a monorepo.
+ */
+export async function collectCommits (root, ref, { dir = null, limit = 400 } = {}) {
+  const range = ref ? `${ref}..HEAD` : 'HEAD'
+  const SEP = '\u001f'; const END = '\u001e'
+  const fmt = `--format=%H${SEP}%P${SEP}%s${SEP}%b${END}`
+  const log = async (args) => ((await out('git', ['log', fmt, ...args], root)) || '').split(END).map((x) => x.trim()).filter(Boolean).map((x) => { const [sha, parents, subject, body = ''] = x.split(SEP); return { sha, parents: parents.split(' ').filter(Boolean), subject, body: body.trim() } })
+  const scope = dir && dir !== '.' ? ['--', dir] : []
+  const first = await log(['--first-parent', `-n${limit}`, range, ...scope])
+  const items = []
+  for (const c of first) {
+    if (c.parents.length > 1) {
+      const pr = c.subject.match(/^Merge pull request #(\d+)/) || c.subject.match(/^Merge branch .* into .*\(#(\d+)\)/) || c.subject.match(/\(#(\d+)\)\s*$/)
+      if (pr) { items.push({ sha: c.sha, subject: c.body.split('\n')[0] || c.subject, body: c.body.split('\n').slice(1).join('\n'), pr: { number: Number(pr[1]), url: null } }); continue }
+      for (const inner of await log(['--no-merges', `-n${limit}`, `${c.parents[0]}..${c.sha}`, ...scope])) items.push({ sha: inner.sha, subject: inner.subject, body: inner.body, pr: null })
+      continue
+    }
+    const sq = c.subject.match(/\(#(\d+)\)\s*$/)
+    items.push({ sha: c.sha, subject: c.subject, body: c.body, pr: sq ? { number: Number(sq[1]), url: null } : null })
+  }
+  // links and titles of pull requests (GitHub)
+  const repo = await repoSlug(root)
+  const numbers = [...new Set(items.map((i) => i.pr?.number).filter(Boolean))]
+  if (repo?.host === 'github') {
+    let titles = new Map()
+    if (numbers.length && process.env.KALOKO_NO_GH !== '1') {
+      const json = await out('gh', ['pr', 'list', '--state', 'merged', '--limit', '200', '--json', 'number,title,url'], root, 15000)
+      try { titles = new Map(JSON.parse(json || '[]').map((p) => [p.number, p])) } catch {}
+    }
+    for (const i of items) {
+      if (!i.pr) continue
+      const p = titles.get(i.pr.number)
+      i.pr.url = p?.url || `https://github.com/${repo.slug}/pull/${i.pr.number}`
+      // a squash commit or merge keeps its own title unless it is GitHub's default "Merge pull request" line
+      if (p?.title && /^Merge pull request/.test(i.subject)) i.subject = p.title
+    }
+  }
+  return items
+}
+
+// ---------- the draft ----------
+
+/**
+ * The draft entry of a product: commits and pull requests since the last release plus the steps that accepted runs
+ * show differently (when a service client is given). Returns { product, since, source, commits, changes, groups,
+ * markdown, internal, service, file }.
+ */
+export async function draftChangelog ({ root, config, product, since = null, client = null }) {
+  const file = changelogFile(root, product)
+  const text = (await readText(file)) || ''
+  const src = await detectVersionSource(root, product)
+  const from = await sinceRef(root, product, src, since, text)
+  const dir = product.version?.path ? dirname(product.version.path) : null
+  const commits = await collectCommits(root, from.ref, { dir })
+  let changes = []; let service = 'offline'; let previous = null
+  if (client && config.org) {
+    try {
+      const q = new URLSearchParams({ product: product.slug, ...(from.version && since ? { since: from.version } : {}) })
+      const r = await client.request('GET', `/orgs/${config.org}/changelog/changes?${q}`)
+      changes = (r.scenarios || []).map((s) => ({ scenario: s.scenario, title: s.title, steps: (s.steps || []).map((st) => ({ ...st, pr: st.pr ?? s.run?.pr?.number ?? null })) }))
+      previous = r.previous || null
+      service = 'ok'
+    } catch (e) { service = `error: ${String(e.message || e).split('\n')[0].slice(0, 200)}` }
+  }
+  const d = draftEntry({ commits, changes })
+  return { product: product.slug, since: from, previous, source: src, commits: commits.length, changes, groups: d.groups, markdown: d.markdown, internal: d.internal, service, file }
+}
+
+/** The draft as an Unreleased section, with a note for whoever edits it. */
+export function draftText (d) {
+  if (!d.markdown) return '## [Unreleased]\n\n<!-- Nothing user-facing since the last release: no merged changes and no changed screens. -->\n'
+  return `## [Unreleased]\n\n<!-- Draft by kaloko changelog draft: write each line for the people who use the product (what they can do now,\n     what looks different), one change per line; delete what is internal; keep the step references for the pictures. -->\n\n${d.markdown}\n`
+}
+
+/** Writes the draft into the changelog's Unreleased section (creating the file with the skeleton when missing). */
+export async function applyToChangelog (d) {
+  if (d.source.owns_changelog) throw new UserError(`${d.source.tool} writes ${relative(process.cwd(), d.file) || 'CHANGELOG.md'}; kaloko leaves it to it. Use the printed draft in your pull request or release notes, and kaloko release reads the entry ${d.source.tool} writes.`)
+  const before = (await readText(d.file)) || ''
+  const { text, added } = applyDraft(before || CHANGELOG_SKELETON, d.groups)
+  if (text !== before) await writeFile(d.file, text)
+  return { added, created: !before }
+}
+
+// ---------- the release ----------
+
+/**
+ * Records a release on the service: the product (from the config), the version (given, else the version source's),
+ * the entry of that version in the changelog (an Unreleased section becomes the release unless a release tool owns
+ * the file; --no-write leaves the file alone) and the runs, which the service picks (newest accepted run per flow)
+ * unless `runs` names them. Returns what happened, for the CLI to say.
+ */
+export async function releaseProduct ({ root, config, product, version = null, date = null, client, write = true, runs = null, dryRun = false }) {
+  const src = await detectVersionSource(root, product)
+  const v = cleanVersion(version || src.version || '')
+  if (!v) throw new UserError(`Which version? Pass it (kaloko release 2.4.0); ${src.source === 'git-tag' ? `no tag matches ${src.pattern}` : `${src.path || src.source} names none`}.`)
+  if (!/^[0-9A-Za-z][0-9A-Za-z.+-]{0,79}$/.test(v)) throw new UserError(`Not a version: ${v}`)
+  const notes = []
+  if (src.version && src.version !== v && src.source !== 'git-tag' && src.source !== 'semantic-release') notes.push(`${src.tool || src.source} (${src.path}) says ${src.version}; recording ${v} as you asked.`)
+  const file = changelogFile(root, product)
+  let text = (await readText(file)) || ''
+  let section = sectionOf(text, v)
+  let finalized = false
+  const day = /^\d{4}-\d{2}-\d{2}$/.test(date || '') ? date : section?.date || today()
+  if (!section && write && !src.owns_changelog && sectionOf(text, null)?.body?.trim()) {
+    const f = finalizeRelease(text, v, day, { tagPattern: src.pattern })
+    if (f.changed) {
+      if (!dryRun) await writeFile(file, f.text)
+      text = f.text; section = sectionOf(text, v); finalized = true
+    }
+  }
+  if (!section) notes.push(`${relative(root, file) || 'CHANGELOG.md'} has no entry for ${v}${src.owns_changelog ? ` (${src.tool} writes it)` : ''}; the release is recorded without text.`)
+  const md = section?.body || ''
+  const refs = findStepRefs(md)
+  const broken = refs.filter((r) => !r.parsed).map((r) => r.ref)
+  if (broken.length) notes.push(`Broken step references: ${broken.join(', ')}`)
+  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)) },
+    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 }
+  const saved = await client.request('POST', `/orgs/${config.org}/products`, payload.product)
+  notes.push(...(saved.notes || []))
+  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 }
+}
+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}` } : {}
+}
+
+// ---------- init and doctor ----------
+
+/** The config block `kaloko init --docs=changelog|full` adds (comments say what each line does). */
+export function docsConfigBlock ({ products = null } = {}) {
+  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 (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 }`)
+  }
+  return `${lines.join('\n')}\n`
+}
+
+/** Apps of a monorepo that look like products (apps/* with a package.json), for kaloko init. */
+export async function detectProducts (root) {
+  const out = []
+  for (const base of ['apps']) {
+    const names = await readdir(join(root, base)).catch(() => [])
+    for (const n of names.sort()) {
+      const pkg = await readJson(join(root, base, n, 'package.json'))
+      if (pkg) out.push({ slug: slugOf(n), name: pkg.name ? String(pkg.name).replace(/^@[^/]+\//, '') : n, dir: `${base}/${n}`, path: `${base}/${n}/package.json` })
+    }
+  }
+  return out.length > 1 ? out : []
+}
+
+/** Diátaxis folders and an index for `kaloko init --docs=full` (only what is missing). */
+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'
+}
+
+/**
+ * Doctor checks for products: each product's version resolves from its source, scenarios name a known product
+ * (and module), and with several products every scenario says which one it shows. [{ name, ok, detail, hint }]
+ */
+export async function productChecks ({ config, root, scenarios = [] }) {
+  const checks = []
+  const products = Object.keys(config.products || {})
+  if (!products.length) return checks
+  for (const p of productsOf(config, root)) {
+    const src = await detectVersionSource(root, p)
+    const ok = !!src.version || src.source === 'manual'
+    checks.push({ name: `product ${p.slug}`, ok, detail: ok ? `version ${src.version || '(set by kaloko release)'} from ${src.source}${src.path ? ` (${src.path})` : src.source === 'git-tag' ? ` (${src.pattern})` : ''}` : `no version from ${src.source}${src.path ? ` (${src.path})` : ` (${src.pattern})`}`, hint: ok ? '' : src.source === 'git-tag' ? `Tag a release (git tag ${tagFor(src.pattern, '1.0.0')}) or set products.${p.slug}.version.` : `Set the version in ${src.path || src.source}, or products.${p.slug}.version in the config.` })
+  }
+  const untagged = []; const unknown = []
+  for (const s of scenarios) {
+    if (!s.product) { untagged.push(s.file); continue }
+    if (!products.includes(s.product)) unknown.push(`${s.file}: product ${s.product}`)
+    else if (s.module && !(config.products[s.product].modules || []).includes(s.module)) unknown.push(`${s.file}: module ${s.module} of ${s.product}`)
+  }
+  if (unknown.length) checks.push({ name: 'scenario products', ok: false, detail: unknown.slice(0, 5).join('; '), hint: 'Use a key of products: (and one of its modules:) in the scenario.' })
+  if (untagged.length && products.length > 1) checks.push({ name: 'scenario products', ok: false, detail: `${untagged.length} scenario(s) without product: ${untagged.slice(0, 4).join(', ')}${untagged.length > 4 ? ' …' : ''}`, hint: `Add product: <${products.join('|')}> to each, so their pictures go to the right changelog.` })
+  else if (!unknown.length) checks.push({ name: 'scenario products', ok: true, detail: products.length === 1 ? `untagged scenarios belong to ${products[0]}` : 'every scenario names its product' })
+  return checks
+}

package/src/lib/doctor.mjs

@@ -12,6 +12,7 @@ import { DEFAULTS as JEV } from './jev.mjs'
 import { visionSettings, VISION_WEIGHT } from './vision-core.mjs'
 import { serviceUrl } from './service.mjs'
 import { videoTools, recordingChecks } from './video.mjs'
+import { productChecks } from './changelog.mjs'
 
 const portFree = (port) => new Promise((done) => {
   const s = createServer().once('error', () => done(false)).once('listening', () => s.close(() => done(true)))
@@ -36,8 +37,9 @@ async function reach (url, fetchImpl, ms = 6000, headers = {}) {
  * @param {string[]} [o.engines] browser engines the scenarios and config.walk ask for (webkit, firefox)
  * @param {Function} [o.launchEngine] async (engine) => { version } — throws when the engine is not installed
  * @param {object} [o.tools] app tools found (default: looked up on PATH)
+ * @param {object[]} [o.scenarios] { file, product, module } of the scenario files (products checks)
  */
-export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false, engines = null, launchEngine = defaultEngine, tools = null, os = process.platform, videoToolsImpl = null }) {
+export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false, engines = null, launchEngine = defaultEngine, tools = null, os = process.platform, videoToolsImpl = null, scenarios = [] }) {
   const checks = []
   const add = (name, ok, detail = '', hint = '') => checks.push({ name, ok, detail, hint })
 
@@ -165,6 +167,9 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
   // recordings (batch D): ffmpeg and the device recorders, with install hints per OS
   checks.push(...recordingChecks({ config, tools: await (videoToolsImpl || videoTools)() }))
 
+  // the visual changelog: each product's version resolves and scenarios say which product they show
+  checks.push(...await productChecks({ config, root, scenarios }))
+
   return { ok: checks.every((c) => c.ok), checks }
 }
 

package/src/lib/run.mjs

@@ -28,7 +28,7 @@ export function newRunId (scenario, date = new Date()) {
   return { id: `${today(date)}-${slugify(scenario.id)}-${short}`, short }
 }
 
-export async function createRun ({ output, scenario, scenarioFile, env, scope, git, executor, root, project = null, issue = null, appVersion = null }) {
+export async function createRun ({ output, scenario, scenarioFile, env, scope, git, executor, root, project = null, issue = null, appVersion = null, product = null }) {
   const { id, short } = newRunId(scenario)
   const dir = resolve(root, output, id)
   await mkdir(dir, { recursive: true })
@@ -36,7 +36,7 @@ export async function createRun ({ output, scenario, scenarioFile, env, scope, g
     id,
     short,
     scenario_file: relative(root, scenarioFile),
-    scenario: { id: scenario.id, title: scenario.title, kind: scenario.kind || 'task', version: scenario.version ?? null, source: scenario.source ?? null, ...(scenario.archived ? { archived: true } : {}), ...(scenario.readonly ? { readonly: true } : {}), ...(scenario.platform && scenario.platform !== 'web' ? { platform: scenario.platform } : {}) },
+    scenario: { id: scenario.id, title: scenario.title, kind: scenario.kind || 'task', version: scenario.version ?? null, source: scenario.source ?? null, ...(scenario.archived ? { archived: true } : {}), ...(scenario.readonly ? { readonly: true } : {}), ...(scenario.platform && scenario.platform !== 'web' ? { platform: scenario.platform } : {}), ...(product || scenario.product ? { product: product || scenario.product } : {}), ...(scenario.module ? { module: scenario.module } : {}) },
     environment: { name: env.name, base_url: env.base_url, readonly: env.readonly, ...(env.kind === 'design' ? { kind: 'design' } : {}) },
     scope,
     git,