kaloko 0.5.1 → 0.6.0

package/skills/kaloko/reference/docs.md

@@ -0,0 +1,246 @@
+# 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.
+
+## 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
+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`) 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.
+
+## 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),
+`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

@@ -33,9 +33,13 @@ 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 |
+| `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
@@ -49,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).
@@ -76,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.