kaloko 0.5.2 → 0.6.0

package/README.md

@@ -238,6 +238,59 @@ 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`.
 
+When release-please, changesets or semantic-release makes your releases,
+`npx kaloko ci github --release` adds a workflow that records each published
+release on Kaloko; your release tool keeps writing `CHANGELOG.md`.
+
+## Docs that keep up with the app
+
+Guides in your `docs/` folder (tutorials, how-to guides, reference,
+explanation) use the same step references, so their pictures never go stale.
+A Czech translation of `pay.md` is `pay.cs.md` next to it.
+
+```bash
+npx kaloko init --docs=full           # docs folders with a template in each
+npx kaloko docs check                 # broken references, stale sections, missing translations; exit 1 in CI
+npx kaloko docs publish               # the docs on kaloko.app: versions, languages, screens, search
+npx kaloko export --format docusaurus # or md, vitepress, mkdocs, html, pdf, json: pictures as files
+```
+
+When a screen changes after its guide was written, the section on kaloko.app
+says "the screen changed in 2.4 — check the text", and `kaloko docs check`
+lists it. A guide plays as a walkthrough, one step at a time, and readers can
+ask for a "What's new" e-mail with every release.
+
+## Jira, Linear, Slack and Teams
+
+When a reviewer returns a step, the fix usually gets planned in Jira or
+Linear. Create the issue from the step, on the canvas or from the terminal:
+
+```bash
+npx kaloko issue create --step checkout --to jira --criterion AC2
+```
+
+The issue gets the screenshot, the criterion, the reviewers' notes and a link
+back to the step. When it is done in the tracker, the comment on the step is
+resolved. A branch or pull request title that names the issue (`WEB-12`, or
+Linear's `eng-42`) links the run to it. Slack and Teams channels are chosen per
+project in Settings → Integrations, with the events each channel wants and
+quiet hours.
+
+## Pages checked on a schedule
+
+A read-only scenario of public or gated pages can run on Kaloko's own
+browsers every morning, with nobody starting the CLI (Business plan):
+
+```bash
+npx kaloko schedule add --scenario qa/flows/public.yml --env production --every day --at 5
+npx kaloko schedule export github --scenario qa/flows/checkout.yml --env staging   # the full walk in GitHub Actions
+```
+
+Hosted runs open pages (HTTP Basic and saved sessions work), take full-page
+screenshots in every locale and viewport and check selectors and text. Steps
+that click or type, apps and local environments need the full walk, which the
+exported workflow runs on the same schedule.
+
 ## Design (Kaloko Design)
 
 Design the screens of a flow as live HTML with your own agent and skills, in the same scenario that development
@@ -266,6 +319,28 @@ npx kaloko spec payment                   # elements, styles → tokens, states
 npx kaloko walk && npx kaloko drift       # expected token vs actual value per element; exit 1 while it differs
 ```
 
+Each published version says what changed since the previous one, step by step: the text that moved, the
+viewports that look different, the tokens that changed. Read it before publishing and write your own where the
+reason matters:
+
+```bash
+npx kaloko share --notes-preview          # what the version notes would say
+npx kaloko share --notes notes.md         # a summary, then "step-id: what changed" lines
+```
+
+Design in Figma? Import the frames as design steps and make them the design reference without redrawing them.
+Frames match steps by name (`Payment / mobile`); each step gets the frame image, its text layers with their type
+and colors, and the file's variables as `tokens.json`. It goes one way: prototype links and components stay in
+Figma. Without an API token, import a folder of frames exported from Figma.
+
+```bash
+FIGMA_TOKEN=figd_… npx kaloko design import figma "https://www.figma.com/design/<key>/Shop" --scenario qa/flows/checkout.yml
+npx kaloko design import figma ./figma-export --scenario qa/flows/checkout.yml
+```
+
+Looking for where a pattern is already used? `npx kaloko screens "empty cart"` searches the newest screenshot of
+every step across your flows (also at `/<org>/screens` on kaloko.app and MCP `search_screens`).
+
 On the canvas, *Prototype* (or `P`) presents the steps full screen as live pages: click through links between
 steps, switch the device, walk with the arrow keys, and share a link that opens straight into a step. The rules
 for pages that work everywhere are in `skills/kaloko/reference/portable-html.md`.

package/package.json

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

package/schemas/changelog.v1.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qawalk.com/schemas/changelog.v1.json",
+  "title": "qawalk.changelog.v1",
+  "description": "The visual changelog as data (docs/DOCS-CHANGELOG.md → Exports): releases newest first with their Keep a Changelog groups and items, each item with the pictures its step references resolve to. Written by src/lib/docs-export.mjs changelogJson; served by GET …/docs/export?format=json and the Download menu of the changelog and docs pages; kaloko export --format json saves it. image is a link for the reader who exported it (signed links expire); canvas opens the step on Kaloko when the reader may see the run.",
+  "type": "object",
+  "required": ["schema", "product", "releases"],
+  "properties": {
+    "schema": { "const": "qawalk.changelog.v1" },
+    "product": {
+      "type": "object",
+      "required": ["slug"],
+      "properties": {
+        "slug": { "type": "string" },
+        "name": { "description": "A name, or names per language ({ \"en\": …, \"cs\": … }).", "oneOf": [{ "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" }] }
+      }
+    },
+    "generated_at": { "type": ["string", "null"], "format": "date-time" },
+    "releases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["version", "groups"],
+        "properties": {
+          "version": { "type": "string" },
+          "released_on": { "type": ["string", "null"], "description": "YYYY-MM-DD" },
+          "tag": { "type": ["string", "null"] },
+          "notes": { "type": "string", "description": "Text before the first group." },
+          "groups": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["name", "items"],
+              "properties": {
+                "name": { "type": "string", "description": "Added, Changed, Deprecated, Removed, Fixed, Security, or the heading as written." },
+                "heading": { "type": "string" },
+                "items": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": ["text", "pictures"],
+                    "properties": {
+                      "text": { "type": "string", "description": "The item's words without pictures and comments." },
+                      "pictures": {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "required": ["ref", "ok"],
+                          "properties": {
+                            "ref": { "type": "string", "description": "The step reference kaloko:<scenario>/<step>[?…]." },
+                            "ok": { "type": "boolean", "description": "false: no accepted picture for this reference." },
+                            "scenario": { "type": "string" },
+                            "step": { "type": "string" },
+                            "title": { "type": ["string", "null"] },
+                            "locale": { "type": "string" },
+                            "viewport": { "type": "string" },
+                            "run": { "type": ["string", "null"] },
+                            "version": { "type": ["string", "null"], "description": "The release the picture belongs to (null: the newest accepted)." },
+                            "image": { "type": ["string", "null"] },
+                            "canvas": { "type": ["string", "null"] }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "docs": {
+      "type": "array",
+      "description": "The docs pages in the export (one language).",
+      "items": {
+        "type": "object",
+        "required": ["path", "title"],
+        "properties": { "path": { "type": "string" }, "lang": { "type": ["string", "null"] }, "title": { "type": "string" }, "kind": { "type": ["string", "null"], "enum": ["tutorials", "how-to", "reference", "explanation", null] } }
+      }
+    }
+  }
+}

package/schemas/run.v1.json

@@ -275,6 +275,13 @@
         "number": {
           "type": "integer"
         },
+        "key": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Jira or Linear issue key (ENG-42) from the scenario, the branch or the pull request title."
+        },
         "url": {
           "type": [
             "string",
@@ -329,6 +336,18 @@
       },
       "description": "Steps whose revision differs from the parent version."
     },
+    "notes": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "description": "\"What changed\" notes of a design version (qawalk.version-notes.v1): summary and steps [{ step, title, locales, reason, changes, text }]; generated texts are { en, cs }, edited ones a string.",
+      "properties": {
+        "schema": { "const": "qawalk.version-notes.v1" },
+        "summary": { "type": ["string", "object", "null"] },
+        "steps": { "type": "array", "items": { "type": "object", "required": ["step"], "properties": { "step": { "type": "string" }, "reason": { "enum": ["new", "changed", "removed", "note"] }, "text": { "type": ["string", "object"] } } } }
+      }
+    },
     "draft": {
       "type": "object",
       "description": "Present when the manifest is a live draft, not a run."

package/schemas/scenario.v1.json

@@ -113,7 +113,7 @@
     "issue": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Ticket the scenario verifies. `number` alone resolves against the repository's remote.",
+      "description": "Ticket the scenario verifies. `number` alone resolves against the repository's remote; `key` names a Jira or Linear issue (ENG-42).",
       "properties": {
         "repo": {
           "type": "string",
@@ -123,6 +123,11 @@
           "type": "integer",
           "minimum": 1
         },
+        "key": {
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]{0,19}-[1-9][0-9]{0,8}$",
+          "description": "Jira or Linear issue key, e.g. ENG-42."
+        },
         "url": {
           "type": "string"
         },

package/skills/kaloko/SKILL.md

@@ -13,12 +13,14 @@ description: >
   reviewer rejected on a canvas, what is waiting in the Kaloko inbox, or how
   to report a run in an issue, and when designing screens of a flow in a
   design environment (live HTML steps, drafts, versions, the design
-  reference, checking implementation against it), and when implementing a
+  reference, checking implementation against it, importing Figma frames),
+  when looking for existing screens across flows, 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), 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 changelog draft, kaloko release) or a guide should show a step or
+  be written, translated or checked (kaloko docs check).
 ---
 
 # Kaloko
@@ -44,6 +46,10 @@ the canvas, storage and collaboration are the service.
   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 the project keeps docs (`docs.dir`, a `docs/` folder with step
+  references) and the change is user-visible: the guides that show the changed
+  screens say what people see now, their translations follow, and
+  `kaloko docs check` reports no broken references or stale sections.
 - 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
@@ -51,7 +57,8 @@ the canvas, storage and collaboration are the service.
 - On a design environment: the folder follows the bundle rules and
   `kaloko design lint` shows no error, `kaloko walk` and `kaloko sync` ran,
   `kaloko status` shows no conflict, and you read the draft's feedback; a
-  version is published only when the person asked.
+  version is published only when the person asked, with notes that say what
+  changed and why (`kaloko share --notes-preview`, then `--notes`).
 
 ## You may do without asking
 
@@ -69,7 +76,9 @@ 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.
+--apply`) and add step references to it and to guides. Write, translate and fix
+guides in the docs folder, run `kaloko docs check`, and export them for a docs
+site (`kaloko export --format …`) into a local folder.
 
 ## Ask first
 
@@ -80,7 +89,10 @@ 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,
-recording a release (`kaloko release`) or asking to publish a changelog, and
+recording a release (`kaloko release`) or asking to publish a changelog,
+publishing docs (`kaloko docs publish`, `--reviewed` above all: it says a
+person checked the text), writing a release workflow (`kaloko ci github
+--release`), 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
@@ -130,9 +142,14 @@ 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)
+- Filing a returned step or a failing criterion in Jira or Linear, issue keys in
+  branches, channels per project, and hosted runs of read-only scenarios on a
+  schedule (`kaloko issue`, `kaloko schedule`):
+  [reference/integrations.md](reference/integrations.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:
+  drafting the Unreleased entry, Diátaxis templates, translations, stale sections
+  and `kaloko docs check`, training guides, exports, release tools in CI,
+  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):
@@ -141,6 +158,10 @@ they can do; never write secrets into the config, a scenario or a script.
   references, handoff, tokens, the design pack, canvas edits, branches, HTML
   view, presenting the prototype, exports, bringing your own design skill):
   [reference/design.md](reference/design.md)
+- Bringing Figma frames in as design steps and the design reference
+  (`kaloko design import figma`), notes on what changed in a version, and
+  finding existing screens across flows (`kaloko screens`):
+  [reference/design.md#import-from-figma](reference/design.md#import-from-figma)
 - Implementing a screen from the approved design: read the step spec, build
   with its tokens, walk, check drift, fix:
   [reference/design.md#implement-from-the-approved-design](reference/design.md#implement-from-the-approved-design)

package/skills/kaloko/reference/design.md

@@ -95,6 +95,8 @@ color_schemes: [light, dark]
   on both sides is a conflict: name it with `--mine <step>` or `--theirs <step>`; never delete to resolve.
 - `kaloko share` on a design environment publishes a version of the flow (`v4 · 3 changed, 17 unchanged`).
   A version counts as a shared run. Publish when the person asks, not after every change.
+- Every version gets notes on what changed since the previous one; see
+  [What changed in a version](#what-changed-in-a-version).
 - Step status (`in progress`, `ready for review`, `ready for dev`) is set in the canvas or with MCP
   `set_step_status`; `ready for dev` notifies followers.
 - Set `KALOKO_AGENT=<your name>` so people see your writes as yours in presence, history and audit.
@@ -121,6 +123,59 @@ opens straight into the presentation of that step: share it with the person who
   relative links click through there too.
 - A link's query and hash travel to the next step (`../payment/index.html?plan=pro#card`): keep prototype state there.
 
+## What changed in a version
+
+When a version is published, Kaloko writes a short note per changed step against the previous version of the
+branch: a new or removed step, the text that changed (from the step spec), the viewports whose screenshot looks
+different, a new token set, or "looks the same; only the page code changed". Reviewers read it in the version's
+side panel and in the step detail; followers get the summary in their inbox.
+
+- Read what it would say before you publish: `kaloko share --notes-preview` (MCP `get_version_notes` with
+  `version: draft`).
+- Say why, not only what: write a file with a summary first and then `step-id: what changed and why` lines, and
+  publish with `kaloko share --notes notes.md` (or `--notes -` from standard input; MCP `publish_version` takes
+  `notes`). Your text replaces the generated one for the steps you name; the other steps keep theirs.
+- Fix them afterwards with MCP `set_version_notes` or `PUT …/scenarios/<id>/versions/v4/notes`. Plain language for
+  the people who review the design: what they will notice, not file names.
+
+## Import from Figma
+
+Teams whose design lives in Figma can make it the design reference without redrawing it:
+
+```bash
+export FIGMA_TOKEN=figd_…   # Figma → Settings → Security → Personal access tokens (file content: read-only)
+kaloko design import figma "https://www.figma.com/design/<key>/Shop?node-id=12-0" --scenario qa/flows/checkout.yml
+```
+
+- Frames match steps by name: a frame named after the step id or title, with a viewport or locale in it
+  (`Payment / mobile`, `payment@desktop`, `Košík [cs]`). Several frames of one step without a viewport in the name
+  take the viewport of their width. Anything else: `--map frames.json` (`{ "Frame 12": "payment" }`, or
+  `{ "step": "payment", "viewport": "mobile", "locale": "cs" }`, or `{ "skip": true }`). `--frames a,b` and
+  `--page <name>` narrow the import; `--dry-run` shows the matches without writing.
+- Each step gets `<step>/index.html` with the frame's PNG (1× and 2×) and, under it, the frame's text layers as
+  real text with Figma's typography and colors (`var(--token)` where a layer uses a variable or style), so
+  `kaloko spec` and `kaloko drift` have elements to compare. `figma.json` says which frame a page came from.
+- Variables become `tokens.json` (W3C DTCG; extra modes such as dark as mode groups); without variables, the color
+  and text styles the frames use. A `tokens.json` you wrote yourself stays unless you pass `--tokens write`.
+- Steps written by hand are not replaced without `--force`. Importing again replaces what the last import wrote;
+  unchanged frames give the same files, so the next version shows them unchanged.
+- No API token: export the frames from Figma as PNG (1× and 2×) or SVG into a folder and import the folder
+  (`kaloko design import figma ./export`); a `*.tokens.json` in it becomes the token set.
+- Then walk and share as usual, or add `--publish` (start, walk and share in one go). Once a person accepts the
+  version, set it as the design reference: implementation runs with `packs: [design]` are checked against the
+  frames (`design_pixels`) and the text styles and tokens (`kaloko drift`).
+- One way only: prototype links, components, auto layout and interactions do not come over, and nothing goes
+  back to Figma. A frame wider or narrower than its viewport is compared as it is; draw a frame per viewport for a
+  clean pixel comparison.
+
+## Screen library
+
+The newest screenshot of every step across the organization's flows, searchable: `/<org>/screens` on the service,
+`kaloko screens [words]` (`--project`, `--locale`, `--viewport`, `--status fail`, `--designs` for design versions,
+`--json`), MCP `search_screens`. Search matches step and flow titles, ids, paths, URLs, page titles and the H1,
+without caring about diacritics. Use it to find where a pattern is already used before designing a new one, and
+link the screens you reuse in your notes.
+
 ## References
 
 - The design reference is an accepted version: `kaloko reference --design --version 4` (a person accepts the

package/skills/kaloko/reference/docs.md

@@ -82,6 +82,124 @@ A how-to guide (`docs/how-to/pay-with-apple-pay.md`):
 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.
 
+## Living docs
+
+Guides live in the docs folder (`docs.dir`, default `docs/`; per product `products.<p>.docs.dir`), sorted the
+Diátaxis way. Pick the folder by what the reader wants, not by the feature:
+
+| Folder | The reader wants | Shape |
+|---|---|---|
+| `tutorials/` | to learn by doing, start to finish | one path that always works, a result at the end |
+| `how-to/` | to get one task done | numbered steps, one picture per step people look for |
+| `reference/` | to look a fact up | tables and lists, no story |
+| `explanation/` | to understand why | prose, few pictures |
+
+`index.md` (or `README.md`) is the page of its folder. Front matter is optional: `title` (else the first `# `
+heading), `order` (sidebar position). `kaloko init --docs=full` creates the folders with a template in each
+README (inside a comment, so it never shows).
+
+A tutorial:
+
+```markdown
+---
+title: Your first order
+order: 1
+---
+# Your first order
+
+In ten minutes you will have placed an order and seen it in your account.
+
+1. Open the shop and put a tea in the cart.
+   ![Cart](kaloko:checkout/cart)
+2. Choose **Checkout** and pay with a test card.
+   ![Payment](kaloko:checkout/payment)
+
+You have placed your first order. Next: [track it](../how-to/track-an-order.md).
+```
+
+A reference page:
+
+```markdown
+# Order states
+
+| State | What it means |
+|---|---|
+| Paid | The payment went through; the order waits for packing. |
+| Shipped | The parcel left the warehouse. |
+```
+
+An explanation: plain paragraphs that say why ("Card payments are confirmed the next morning, so a cancelled order
+costs the customer nothing"), with a picture only when it shows the point.
+
+Link pages with relative `.md` links (`[track it](../how-to/track-an-order.md)`); Kaloko and every export rewrite
+them. Keep one task per how-to; split a page that needs two "and then" headings.
+
+### Training guides
+
+A how-to or tutorial is also a walkthrough: on Kaloko, "Walk through it step by step" shows one step at a time,
+full screen, with the step's words as the caption, and readers tick "I tried it". Each list item (or paragraph)
+with a picture becomes one step; a picture on its own line belongs to the words above it; a before/after pair shows
+the after. So for guides people train with: one action per item, the picture right under it, words that make sense
+without the paragraphs around them.
+
+### Translations
+
+Translations sit next to the original: `pay.md` and `pay.cs.md`. `docs.languages: [en, cs]` names the languages;
+the first is the language of the originals. Pictures follow the language of the text (a Czech page shows Czech
+screens) unless a reference names `locale=`.
+
+When you change an original, update its translations in the same change. Translate the words, keep the step
+references as they are. To say which version of the original a translation follows, put the first characters of
+the original's SHA-256 in the translation's front matter (`source_hash: 1a2b3c4d`; `shasum -a 256 pay.md`);
+without it, `kaloko docs check` compares git dates. It reports missing and outdated translations as warnings.
+
+### Stale sections and `kaloko docs check`
+
+`kaloko docs publish` sends the folder to Kaloko as the docs of `latest` (`--version 2.4.0` for a release;
+`kaloko release` publishes the folder for its version by itself). When a page's text changes, Kaloko remembers the
+screen behind each of its references. When an accepted run later shows a different screen, the section reads
+"the screen changed in 2.4 — check the text" for the people who write the docs.
+
+Before a pull request that changes screens, and in CI:
+
+1. `kaloko docs check` (add `--json` to read it as data). Errors: broken references, steps the scenario files do
+   not have, references without an accepted picture, stale sections. Warnings: missing or outdated translations,
+   user-visible changelog items without a picture (mark one with `<!-- no picture -->` when there is nothing to
+   show). Exit code 1 on errors; `--strict` also on warnings.
+2. For each stale section, open the step (`resolve_step_image` or the link on the page), compare, and rewrite the
+   words that no longer fit. Editing the text clears the note at the next `kaloko docs publish`.
+3. If the text still fits, say so to the person; with their go-ahead `kaloko docs publish --reviewed` clears the
+   notes without a text change. Never use `--reviewed` to silence notes you have not read.
+
+MCP: `docs_check` (the same report for the published docs), `get_docs` (the sidebar, or a page with its sections,
+stale sections and training steps).
+
+### Exports
+
+`kaloko export --format md|docusaurus|vitepress|mkdocs|html|pdf|json [--product p] [--version v] [--lang cs]`
+writes the docs and the changelog with the pictures as files: Markdown with an `assets/` folder (any static site),
+a Docusaurus, VitePress or MkDocs folder with sidebars and front matter, offline HTML, a PDF (printed by the
+browser), or the changelog as JSON (`schemas/changelog.v1.json`). `--local` exports the files in the repository
+instead of what was published; `--what docs|changelog` exports one of them. The docs and changelog pages offer the
+same downloads. An existing docs site keeps its own build: export into its folder and commit the result, or run the
+export in its CI.
+
+### Release tools in CI
+
+When release-please, changesets or semantic-release makes the releases, Kaloko follows them:
+`kaloko ci github --release` writes `.github/workflows/kaloko-release.yml`, which runs
+`kaloko release <version> --no-write` whenever a GitHub release is published (all three tools publish one). It
+reads the entry the tool wrote, records the release with its pictures and publishes the docs of that version.
+`kaloko ci github --release --snippet` prints the step to put after the tool's own step instead (release-please:
+`if: steps.release.outputs.release_created`; changesets: `if: steps.changesets.outputs.published == 'true'`;
+semantic-release: right after `npx semantic-release`). On GitLab, call `kaloko release <version> --no-write` in
+the release job. Ask before writing a workflow.
+
+### "What's new" e-mail
+
+Readers subscribe per product on its changelog or docs page (Business). When a release is recorded, they get its
+entry with pictures in their language. Nothing to do in the repository beyond writing the entry for people.
+
 ## Products, modules and versions
 
 Without `products:` in `kaloko.config.yml` the project is the product and `CHANGELOG.md` in the root is its
@@ -115,8 +233,8 @@ reads its entry and never rewrites the file; put your draft into the pull reques
 
 ## 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
+The changelog page (`/<org>/products/<product>/changelog`, or `/<org>/projects/<project>/changelog`) and the docs
+(`…/docs`) are 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.
@@ -124,4 +242,5 @@ 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).
+half of a draft: changed screens with before/after references), `resolve_step_image` (one reference),
+`docs_check` (what needs attention in the published docs), `get_docs` (the docs, or one page).

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

@@ -39,6 +39,7 @@ file.
 | `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 +53,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 +83,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.