kaloko 0.5.0 → 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.0",
+  "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
@@ -52,7 +59,8 @@ Start the shared browser, walk a scenario on a non-production environment,
 create test data there (users, roles, carts), capture screens and e-mails,
 evaluate, build the preview, and fix scenario mechanics (selectors, scripts)
 that do not change what is being accepted, including applying a selector
-proposal with `kaloko walk --heal` when it names the same element. Walk only
+proposal with `kaloko walk --heal` when it names the same element, and pulling
+the regions people drew to ignore into the scenario (`kaloko stability --pull`). Walk only
 the steps a change reaches (`--affected`) and import screenshots into a run. Record steps locally
 (`walk --record`) when a screenshot cannot show what a person has to judge, read traces, and
 export a walkthrough video into the run folder. On a design environment: change
@@ -60,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
 
@@ -69,11 +79,13 @@ 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
-step or accept a run on a person's behalf; report what waits for them
+step or accept a run on a person's behalf, and never hand out a signed
+acceptance record (`kaloko signoff`) for a run a person has not accepted; report what waits for them
 (`kaloko review`, MCP `get_review_queue`) instead. Ask the person
 for secret values (passwords, tokens, gate credentials) and for sign-ins only
 they can do; never write secrets into the config, a scenario or a script.
@@ -118,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/acceptance.md

@@ -342,5 +342,7 @@ design pixel check (`AC801`) leave them out:
 
 Do not guess them: `kaloko walk --stability 3` notes what moves while the
 page sits still, and `kaloko stability` compares the step with earlier runs
-and writes suggestions (see [execution.md](execution.md)). Ignore only noise;
-a region that matters to a criterion stays in.
+and writes suggestions (see [execution.md](execution.md)). Reviewers can also
+draw a region on a screenshot on kaloko.app; `kaloko stability --pull` writes
+those into `ignore:`. Ignore only noise; a region that matters to a criterion
+stays in.

package/skills/kaloko/reference/collaboration.md

@@ -72,8 +72,11 @@ comments; at the end they accept or return the run.
 Comments are threads in three places:
 
 - **A step:** optionally pinned to a position on the screenshot
-  (`pin: {x, y}` as fractions, per viewport) or to an element of a live
-  design step (`anchor`).
+  (`pin: {x, y}` as fractions, per viewport), drawn on it (a box, an arrow or
+  a line: `shape`, with `region` giving the area as fractions and in CSS
+  pixels of the page, and for an arrow the point it aims at), or attached to
+  an element of a live design step (`anchor`). Comments may carry images
+  (`attachments`, each with a download URL that needs the token).
 - **The whole run:** `node_id` is `''`.
 - **The whole flow:** these stay across runs, e.g. "add the empty-cart
   state".
@@ -85,8 +88,12 @@ said what.
 
 The loop, for every open thread:
 
-1. **Understand it.** Open the canvas link when a pin or an element
-   matters; the position is on the screenshot of that viewport and locale.
+1. **Understand it.** A `region` says exactly where to look: `px` is
+   `[x, y, width, height]` in CSS pixels of the captured page for that
+   viewport (`region.viewport`) and locale; find the element there in the
+   step's HTML or screenshot. Download attached images (a corrected copy, a
+   reference) before you change anything. Open the canvas link when a pin or
+   an element matters.
 2. **Fix it** in the code or the scenario. When the comment asks for a
    change of intent (criteria, scope), ask the person first.
 3. **Answer and close.** Use
@@ -181,14 +188,25 @@ e-mail works too). Use it when a step needs a decision from a specific person
   Put the relevant lines in the issue comment. On the canvas the same
   comparison is the **Compare** selector in the top bar (or `#cmp=<run>` in
   the URL): pixel differences per step, changed criteria, and a side-by-side
-  or diff view in the lightbox. Pixel diffs are computed in the browser;
-  nothing is uploaded.
+  or diff view in the lightbox, plus *Swipe* (a divider dragged across both
+  screenshots) and *Onion skin* (this run faded over the other). Pixel diffs
+  are computed in the browser; nothing is uploaded. **G** opens the grid: one
+  step in every locale and viewport at once, failing cells marked.
 - **Manual criteria** are decided on the canvas by a reviewer; treat a
   reviewer's `fail` like a failing deterministic check.
 - Admins may name **required approvers** per scenario (Settings). Such a
   run stays `pending` until every one of them approved; `kaloko feedback`
   prints `awaiting approval from: …`, so do not treat a single approval as
   acceptance there.
+- An accepted run has a **signed acceptance record** (Business and up): the
+  run, scenario, commit and environment, who approved what and when (people
+  apart from tokens and agents, approvals carried over unchanged steps with
+  where they came from), criteria results, capture hashes and the hash of
+  `run.json`, signed with the service's Ed25519 key. `kaloko signoff <run>`
+  downloads the JSON and the PDF and checks them; `kaloko signoff --verify
+  <file>` checks a record someone handed over (public key at
+  `/.well-known/kaloko-signoff.json`). Give it to the person when they ask
+  for proof of acceptance; never create one for a run that is not accepted.
 
 ## Cleaning up runs
 
@@ -245,6 +263,17 @@ Everything above is available over the API with an organization token:
   (the whole flow), and per comment `PATCH`, `DELETE`, `POST …/<cid>/resolve`
   (with `note`) and `…/<cid>/reopen`; `GET /api/v1/orgs/<org>/comments?state=open|all&scenario=&run=&mine=1`
   across the organization. Lists of runs and scenarios carry `open_comments`.
+  A comment body may carry `shape` (`{kind: box, box: [x, y, w, h]}`,
+  `{kind: arrow, from, to}` or `{kind: pen, points}` in fractions, with
+  `viewport` and `size`) and `attachments` (ids from
+  `POST …/comments/attachments?name=<file>` with the image as the body: PNG,
+  JPEG, WebP or GIF up to 5 MB, counted in the plan's storage).
+- `GET|POST /api/v1/orgs/<org>/runs/<id>/ignore-regions`,
+  `DELETE …/ignore-regions/<rid>`, `GET …/scenarios/<id>/ignore-regions[?state=all]`
+  and `POST …/scenarios/<id>/ignore-regions/applied` (`{ids}`): regions drawn
+  to leave out of pixel diffs (drawing needs Developer / Tester).
+- `GET /api/v1/orgs/<org>/runs/<id>/signoff` (JSON), `…/signoff.pdf`,
+  `…/signoff.html`: the signed acceptance record of an accepted run.
 - `GET /api/v1/orgs/<org>/notifications[?unread=1]`, `POST` with
   `{"read": "all"}` or `{"read": [ids]}`
 - `GET /api/v1/orgs/<org>/runs[?project=&scenario=&kind=&verdict=&author=&environment=&branch=&q=][&latest=1]`

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/execution.md

@@ -88,6 +88,7 @@ When pixel diffs between runs keep flagging the same clock, ad or carousel:
 kaloko walk --stability 3        # 3 screenshots per capture, a moment apart; what moved is noted
 kaloko stability                 # this run against the 3 previous local runs of the scenario
 kaloko stability --apply         # adds the suggested ignore: to each step (block-style YAML only)
+kaloko stability --pull          # regions people drew on screenshots on kaloko.app go into ignore:
 ```
 
 `kaloko stability` writes `stability.json` and `stability.yml` into the run
@@ -98,6 +99,14 @@ changed is not noise. `--same-commit` compares only runs of the same commit,
 `--runs a,b` names them, `--last N` sets how many runs are compared. Capture
 the steps again after applying: the capture records the ignored regions.
 
+People mark noise by hand too: a Developer / Tester draws a rectangle on a
+screenshot (step detail → *Mark a changing region*). It is kept per flow, shows
+dashed on every run and the canvas pixel diff already skips it.
+`kaloko stability --pull` writes those regions into the scenario's `ignore:`
+(appended to an existing block list, never twice) and tells the service they
+are in the file; walk those steps again afterwards. MCP `list_ignore_regions`
+lists them, `add_ignore_region` suggests one.
+
 ## Only what changed
 
 After a fix, walk the steps the change reaches instead of the whole flow:

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 |
@@ -42,8 +45,11 @@ file.
 
 | Tool | Use |
 |---|---|
-| `list_comments` | open threads (or `state: all`) across the organization, filtered by `scenario` or `run_id`, with replies, pins, anchors and who wrote them |
-| `add_comment` | comment on a step (`run_id` + `step`), the whole run (`run_id`) or the whole flow (`scenario`); `parent_id` replies; optional `pin` `{ x, y, viewport }` |
+| `list_comments` | open threads (or `state: all`) across the organization, filtered by `scenario` or `run_id`, with replies, pins, anchors, drawn regions (`region.px`: CSS pixels of the page in `region.viewport`), attached images with URLs, and who wrote them |
+| `add_comment` | comment on a step (`run_id` + `step`), the whole run (`run_id`) or the whole flow (`scenario`); `parent_id` replies; optional `pin` `{ x, y, viewport }` or `shape` (box or arrow in fractions, with `viewport` and `size`) |
+| `list_ignore_regions` | regions people drew to leave out of pixel diffs, per step, with the `ignore:` entry each becomes (`kaloko stability --pull` writes them) |
+| `add_ignore_region` | suggest such a region (`run_id`, `step`, `viewport`, `rect` in CSS px); Developer / Tester, scope upload or full |
+| `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 |