kaloko 0.12.2 → 0.14.0

package/README.md

@@ -1,6 +1,7 @@
 # Kaloko
 
-See what your agent built, on one canvas, and sign it off.
+Your AI agents build; Kaloko walks every screen, puts it on one canvas and
+records who approved what.
 
 Your coding agent (Claude Code, Codex or any LLM with a shell) walks your
 acceptance plan with the `kaloko` skill. Kaloko captures every screen and
@@ -169,6 +170,9 @@ messages. Click a row and the video jumps there. Web recordings need nothing
 but Chrome (WebM with VP9); with ffmpeg installed you also get MP4 for Safari,
 app recordings (Android `screenrecord`, iOS Simulator, macOS) and the
 walkthrough export. `npx kaloko video tools` says what this machine has.
+Videos play on: when one ends, the next step's video starts, and replay moves
+to the next step by itself; a step that needs a decision waits for you, and a
+step without video shows its screenshot for three seconds.
 Recordings stay in the local preview on Free and Team; Business and Enterprise
 share them with the run.
 
@@ -219,10 +223,12 @@ Every AI verdict comes with one sentence saying why. Criteria marked
 `vision: true`, and answers the text evaluator is unsure about, get a second
 look at the screenshot from a vision model (`ANTHROPIC_API_KEY`, or through
 Kaloko); `kaloko build` lists what to act on with the score and the reason.
-As an experiment you can switch on in Settings, Clef on Cloudflare also names
-the kind of problem each screen and its recording show (overlap, cut-off text,
-a raw translation key, an endless spinner); reviewers turn the right findings
-into comments with one click, and findings never change a verdict.
+As an experiment an admin switches on under Settings → Security → Experiments,
+Clef on Cloudflare also names the kind of problem each screen and its recording
+show (overlap, cut-off text, a raw translation key, an endless spinner);
+reviewers turn the right findings into comments with one click, and findings
+never change a verdict. Triage counts against the hosted-evaluation allowance,
+so it needs the Team plan or higher.
 The `a11y` pack walks the page with Tab (order, visible focus, traps, skip
 link) and reads names from the accessibility tree. Pixel diffs skip the
 regions a step ignores; `kaloko walk --stability 3` and `kaloko stability`

package/bin/qawalk.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
 import { main } from '../src/cli.mjs'
 
-await main(process.argv.slice(2))
+// the command's name before the rename to Kaloko: it still works and says so once on stderr
+await main(process.argv.slice(2), { bin: 'qawalk' })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kaloko",
-  "version": "0.12.2",
-  "description": "See what your AI agents built: every screen, language and device walked, assessed and approved on one canvas.",
+  "version": "0.14.0",
+  "description": "Your AI agents build; Kaloko walks every screen, puts it on one canvas and records who approved what.",
   "keywords": [
     "qa",
     "acceptance-testing",

package/schemas/changelog.v1.json

@@ -57,6 +57,11 @@
                             "run": { "type": ["string", "null"] },
                             "version": { "type": ["string", "null"], "description": "The release the picture belongs to (null: the newest accepted)." },
                             "image": { "type": ["string", "null"] },
+                            "video": {
+                              "type": "object",
+                              "description": "Present when the accepted run has a recording of the step and the reference does not say media=image: links like image, and the length.",
+                              "properties": { "mp4": { "type": ["string", "null"] }, "webm": { "type": ["string", "null"] }, "duration_ms": { "type": ["number", "null"] } }
+                            },
                             "canvas": { "type": ["string", "null"] }
                           }
                         }

package/schemas/config.v1.json

@@ -226,7 +226,8 @@
         "serve": { "type": "string", "description": "kind: design. Folder with one sub-folder per step (<step>/index.html, optional <step>/<locale>/index.html) and shared files in _shared/; relative to the config." },
         "fixtures": { "type": "string", "description": "kind: design. Folder of JSON fixtures live steps may fetch instead of real APIs; relative to the config." },
         "origins": { "type": "array", "maxItems": 20, "items": { "type": "string", "pattern": "^https://(\\*\\.)?[A-Za-z0-9.-]+(:[0-9]{1,5})?/?$" }, "description": "kind: design. Origins the design loads fonts, stylesheets and images from (https://fonts.googleapis.com, https://*.cdn.example.com). The organization allows them in Settings → Security; kaloko design lint warns about one it does not allow. Scripts never load from them." },
-        "tokens_mode": { "type": "string", "description": "kind: design. Token mode (e.g. light, dark) steps are rendered in; default: the token set's first mode." },
+        "default_token_mode": { "type": "string", "description": "kind: design. Token mode (e.g. light, dark) steps are rendered in and the checks use; default: the token set's first mode. tokens_mode is its older name." },
+        "tokens_mode": { "type": "string", "description": "kind: design. The older name of default_token_mode; still read." },
         "token_modes": { "oneOf": [{ "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$" } }, { "const": false }], "description": "kind: design. Token modes of the token set to render every step in, one capture per mode (keys <viewport>.mode-<name>); tokens_mode is the default and has the plain key. Not set: every mode of the set when it has two or more, except a set of only light and dark (left to color_schemes). false: only tokens_mode." },
         "html_view": { "type": "boolean", "default": false, "description": "Experimental (#42): keep a static HTML view of every capture (assets rehosted, scripts removed, secrets scrubbed). Refused on production unless the environment is readonly." },
         "base_url": {

package/skills/kaloko/SKILL.md

@@ -20,7 +20,10 @@ description: >
   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 or
-  be written, translated or checked (kaloko docs check).
+  be written, translated or checked (kaloko docs check), when screenshots,
+  HTML or recordings must hide personal data (capture masks, pii: redact or
+  pseudonymize, kaloko share stopping on unmasked data), and when a run has
+  Clef triage findings (experimental) to read, mention or answer.
 ---
 
 # Kaloko
@@ -80,7 +83,7 @@ Draft and edit the Unreleased section of the changelog (`kaloko changelog draft
 config on Kaloko (`kaloko products sync`: it records no release) and list them
 (`kaloko products list`). 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.
+site (`kaloko export docs --format …`) into a local folder.
 
 ## Ask first
 
@@ -128,6 +131,12 @@ only when a person says that value may be uploaded.
   (`--heal`): [reference/execution.md](reference/execution.md)
 - Evaluation, JEV thresholds, the vision evaluator and its reasons, reading
   results: [reference/evaluation.md](reference/evaluation.md)
+- Clef triage findings (experimental): what they are, how to report them apart
+  from the verdicts, `get_findings` and `answer_finding`:
+  [reference/evaluation.md#triage-findings-experimental](reference/evaluation.md#triage-findings-experimental)
+- Hiding personal data in captures (`capture.mask`, `pii: redact`,
+  `pseudonymize`, `pii: required` on an environment, the check before sharing):
+  [reference/acceptance.md#capture-quality](reference/acceptance.md#capture-quality)
 - Screenshots, walkthroughs, Playwright reports and traces that an agent or a
   tool already produced, laid out as a run: [reference/import.md](reference/import.md)
 - Video of a step or a whole flow, traces (actions, requests, console) and the

package/skills/kaloko/reference/ci.md

@@ -24,8 +24,9 @@ the deployment):
 2. `kaloko ci preview-url --wait 600 --github-env` finds the preview URL, the
    pull request and its base branch and puts them into `KALOKO_PREVIEW_URL`,
    `KALOKO_PR`, `KALOKO_BASE`;
-3. for each scenario: `kaloko affected --check` skips it when the change does
-   not reach any of its steps, otherwise `start --env preview`,
+3. for each scenario: `kaloko affected --fail-if-none` skips it when the change
+   does not reach any of its steps (workflows written earlier say `--check`,
+   which works the same and prints a note), otherwise `start --env preview`,
    `walk --ephemeral --affected` and `share --pr` (one comment per scenario,
    updated on later pushes).
 
@@ -52,9 +53,10 @@ include `preview`, or `start` refuses them; the command says which.
 `deployment_status` event; `VERCEL_BRANCH_URL`/`VERCEL_URL`,
 `DEPLOY_PRIME_URL`/`DEPLOY_URL` (Netlify), `CF_PAGES_URL`,
 `CI_ENVIRONMENT_URL` (GitLab), `RENDER_EXTERNAL_URL`; then the commit's GitHub
-deployments, skipping production, polled every 10 s up to `--wait` seconds.
-Only the URL goes to stdout, so `export KALOKO_PREVIEW_URL="$(kaloko ci preview-url)"`
-works in any CI.
+deployments, skipping production, polled every 10 s up to `--wait` (seconds,
+or with a unit: `--wait 10m`). Only the URL goes to stdout, so
+`export KALOKO_PREVIEW_URL="$(kaloko ci preview-url)"` works in any CI;
+`--json` prints the URL, its source and the pull request as one JSON object.
 
 ## Affected steps in CI
 
@@ -65,6 +67,39 @@ in the newest shared run of the scenario count too, so a fresh CI checkout
 maps routes as well as a laptop with earlier runs. See
 [execution.md](execution.md#only-what-changed).
 
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | done |
+| `1` | checks found problems, or the command failed (an HTTP error from the service other than 401 too) |
+| `2` | usage error: unknown command or option, missing argument |
+| `3` | the Kaloko service cannot be reached (no connection: offline, DNS, refused, cut off); retrying may help |
+| `4` | no token, or an invalid, expired or revoked one: `kaloko login`, or a new `KALOKO_TOKEN` secret |
+
+A CI step can tell a broken workflow line (2) or a missing secret (4) from a
+failing check (1), and retry only on 3. Checks keep 1: `docs check`, `drift`,
+`design lint`, `affected --fail-if-none`, `validate`. `kaloko help <command>`
+or `kaloko <command> --help` shows the options of one command.
+
+## Machine output
+
+`--json` on a command that prints data makes stdout one JSON document and
+nothing else: progress, notes and warnings go to stderr. An error is one line
+on stderr, `{"error":{"message":"…","code":"…","next":"…"}}`, with the exit
+code above (`code` is `usage`, `unreachable`, `no_token`, `unauthorized`, a
+service reason such as `plan`, or `failed`). Commands with `--json` include
+`start`, `status`, `evaluate`, `build`, `share` (run id and canvas URL),
+`validate`, `scenarios`, `runs`, `review`, `feedback`, `auth list`,
+`browser status`, `ci preview-url` and `affected`.
+
+```bash
+url=$(npx kaloko share --json | jq -r .url)
+```
+
+`kaloko runs --all` follows the service's pages to the last run; `--limit N`
+stops after N and prints the cursor to go on with (`--cursor`) on stderr.
+
 ## Done means
 
 The workflow file and the config change are committed after the person agreed,

package/skills/kaloko/reference/collaboration.md

@@ -197,7 +197,8 @@ e-mail works too). Use it when a step needs a decision from a specific person
 - 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.
+  acceptance there. Those approvers are asked on their own (mail, inbox,
+  Slack or Teams, one reminder); do not ping them again.
 - 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
@@ -278,6 +279,12 @@ Everything above is available over the API with an organization token:
   `{"read": "all"}` or `{"read": [ids]}`
 - `GET /api/v1/orgs/<org>/runs[?project=&scenario=&kind=&verdict=&author=&environment=&branch=&q=][&latest=1]`
   (`latest=1`: the newest run per scenario with `older`), `GET /api/v1/orgs/<org>/runs/<id>`
+- Paging: runs, `comments`, `notifications`, `tokens` and `audit` take
+  `?limit=` and `?cursor=`. The body keeps its shape (an array stays an
+  array); the next page is named in the `X-Next-Cursor` header and in
+  `Link: <…?cursor=…>; rel="next"`, and object answers (`notifications`,
+  `audit`) also carry `next`. No header, no next page. `projects` and
+  `products` answer the complete list.
 - Clean-up: `DELETE …/runs/<id>` (trash), `POST …/runs/<id>/restore`,
   `POST …/runs/<id>/keep` with `{"keep": true|false}`,
   `POST /api/v1/orgs/<org>/runs/prune` with `{ scenario?, project?, environment?, keep_latest: 3, older_than_days?, dry_run: true }`

package/skills/kaloko/reference/design.md

@@ -83,7 +83,7 @@ design/credit/late/index.html
 - `kaloko sync` sends the variants' captures with the step; the published version shows the stack index with every
   variant and its verdict, and each variant opens live in the lightbox.
 - `kaloko design lint` reports a variant folder without its `index.html` as an error.
-- `kaloko export --live` and `export --design` write the variant folders; the design export adds
+- `kaloko export live` and `export design` write the variant folders; the design export adds
   `screenshots/<step>/<variant>/<locale>/<viewport>.webp`.
 - Not for steps whose variants are different screens of a flow: those stay separate steps.
 
@@ -126,7 +126,7 @@ and `_` works). Draw each one so it can be reviewed and built:
 Token modes: when the token set has two or more modes (resolver contexts or mode groups), every step renders in each
 mode. The walk sets the mode's tokens as custom properties on `:root` after the page's own styles and
 `data-kaloko-mode="<mode>"` on `<html>`; a page that switches themes by class can read the attribute. Captures are
-keyed `<viewport>.mode-<name>`; the environment's `tokens_mode` (else the first mode) is the default with the plain
+keyed `<viewport>.mode-<name>`; the environment's `default_token_mode` (older name `tokens_mode`; else the first mode) is the default with the plain
 key, and the canvas switches modes like colour schemes. A set with only `light`/`dark` modes follows the colour
 scheme instead (`color_schemes: [light, dark]`), unless `token_modes` names them. `token_modes: [brand-a, brand-b]` (environment, scenario or `kaloko start
 --token-modes`) picks modes; `false` turns it off. Live view shows the default mode; other modes are screenshots.
@@ -279,7 +279,7 @@ link the screens you reuse in your notes.
 
 Development builds from the design reference:
 
-- `kaloko export --live [--version n] --out design/` writes the live files into a folder.
+- `kaloko export live [--version n] --out design/` writes the live files into a folder.
 - MCP `get_step` (scenario, step, `ref: design`) returns the file list, a signed entry URL, the token set, the
   page structure and open comments; `list_step_changes` names the steps that changed since the last reference.
 - MCP `get_step_spec` (or `kaloko spec <step>`) returns what to build, element by element, with tokens; see
@@ -321,10 +321,11 @@ Everything exports in open formats, readable without Kaloko:
 
 | What | Command | Contents |
 |---|---|---|
-| a design version (or `--draft`, default the design reference) | `kaloko export --design [--version n] --out dir/` or `--out v4.zip` | the live files in the folder layout, `tokens.json` (DTCG), `scenario.yml` (`qawalk.scenario.v1`), `screenshots/<step>/<locale>/<viewport>.webp`, `kaloko.json` (what is where) and `index.html`, a start page that opens from disk |
-| the live files only (the handoff) | `kaloko export --live [--version n] --out design/` | the design folder as the designer wrote it |
-| a shared run | `kaloko export --run <id>` | `run.json`, every capture, the live HTML of design steps (per revision and merged in `live/site/`), comments and verdicts, and `index.html`: the canvas, offline from `file://` |
+| a design version (or `--draft`, default the design reference) | `kaloko export design [--version n] --out dir/` or `--out v4.zip` | the live files in the folder layout, `tokens.json` (DTCG), `scenario.yml` (`qawalk.scenario.v1`), `screenshots/<step>/<locale>/<viewport>.webp`, `kaloko.json` (what is where) and `index.html`, a start page that opens from disk |
+| the live files only (the handoff) | `kaloko export live [--version n] --out design/` | the design folder as the designer wrote it |
+| a shared run | `kaloko export run --run <id>` | `run.json`, every capture, the live HTML of design steps (per revision and merged in `live/site/`), comments and verdicts, and `index.html`: the canvas, offline from `file://` |
 
+The flag forms from before (`kaloko export --design`, `--live`, `--run <id>`) still work.
 When someone asks for the design or the evidence outside Kaloko, export; do not screenshot the canvas.
 
 ## Tokens
@@ -335,7 +336,7 @@ When someone asks for the design or the evidence outside Kaloko, export; do not
   `{ "$ref": "#/json/pointer" }`, `$extends`, `$root` and `$deprecated`. New sets: prefer the object values.
 - Modes (light, dark): a DTCG resolver `design/tokens.resolver.json` (sets plus a `theme` modifier whose
   contexts point at files) wins over `tokens.json`; `push` inlines its files. Older sets with top-level
-  `light`/`dark` groups still work. `tokens_mode` in the environment picks the mode the checks use.
+  `light`/`dark` groups still work. `default_token_mode` (or `tokens_mode`) in the environment picks the mode the checks use.
 - `kaloko tokens validate` reports names with `{`, `}` or `.`, references that point nowhere and values that
   cannot be read; `push` refuses a set with problems, so does the service.
 - `kaloko tokens push` stores the set as the project's next token set version; `pull` gets it.
@@ -377,7 +378,7 @@ the step, then sync.
 
 Experimental, Business plan. `html_view: true` on an app environment keeps a static, script-free copy of each
 captured page (secrets and hidden values removed) that opens in the canvas like a live step, so the inspector
-works on the real product. It is refused on production pages behind a sign-in. `kaloko export --live --views
+works on the real product. It is refused on production pages behind a sign-in. `kaloko export live --views
 --run <id> --out design/` turns those copies into design steps: a redesign that starts from the product.
 
 ## Bring your own design skill

package/skills/kaloko/reference/docs.md

@@ -13,13 +13,19 @@ A picture in Markdown names a step instead of a PNG file:
 ![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:checkout/payment?media=video)           the step's recording plays on the picture
 ![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
+capture keys like `mobile.webkit.dark`). When the accepted run has a recording of the step (`kaloko walk --record`),
+docs, changelog and training mode show the picture with a play button and play the recording on a click; exports
+carry it, the PDF and the "What's new" mail show the picture. `media=video` says the step needs its recording
+(`kaloko docs check` warns under `no_recording` when the run has none: walk the step with `--record` and have the
+run accepted); `media=image` never plays it. Use `media=video` for interactions a picture cannot show (drag and drop,
+a dialog, a language switch), not for every step. Check a reference with MCP `resolve_step_image` or
+`GET /api/v1/orgs/<org>/steps/resolve?ref=…`: it answers the signed image URL (and `video` with `mp4`, `webm` and `duration_ms` when it plays), 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.
@@ -176,7 +182,7 @@ stale sections and training steps).
 
 ### Exports
 
-`kaloko export --format md|docusaurus|vitepress|mkdocs|html|pdf|json [--product p] [--version v] [--lang cs]`
+`kaloko export docs --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

package/skills/kaloko/reference/documentation.md

@@ -17,7 +17,7 @@ rebuilt from the newest accepted run instead of screenshotting by hand.
 
 ## Stable URLs
 
-With an organization token (`Authorization: Bearer qwk_…`, a read-only
+With an organization token (`Authorization: Bearer kal_…`, a read-only
 viewer token is enough):
 
 ```
@@ -47,8 +47,10 @@ scenarios.
 Settings → Integrations → Webhooks (admin): an https URL and the events
 `run.accepted` and/or `run.shared`. Each call is a JSON POST
 `{ id, type, created_at, org, data: { run, steps, steps_url, changes_url } }`
-with `QAwalk-Signature: t=<unix time>,v1=<hex HMAC-SHA256 of "<t>.<body>">`
-signed with the webhook's secret (copy it from Settings). Verify the
+with `Kaloko-Signature: t=<unix time>,v1=<hex HMAC-SHA256 of "<t>.<body>">`
+signed with the webhook's secret (copy it from Settings). The old
+`QAwalk-Signature` header is still sent with the same value, so existing
+receivers keep working; read `Kaloko-Signature` in new code. Verify the
 signature and the time (reject older than 5 minutes), answer 2xx within 5
 seconds, and do the work asynchronously. Also over the API:
 `GET|POST /api/v1/orgs/<org>/webhooks`, `DELETE …/webhooks/<id>`.
@@ -56,7 +58,7 @@ seconds, and do the work asynchronously. Also over the API:
 ## Export into a folder
 
 ```bash
-npx kaloko export --scenario checkout --accepted --out docs/assets/checkout
+npx kaloko export steps --scenario checkout --accepted --out docs/assets/checkout
 ```
 
 writes `steps/<step>/<locale>/<viewport>.<ext>` and `.html` plus

package/skills/kaloko/reference/integrations.md

@@ -33,10 +33,17 @@ 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.
+each wants (new run, returned, accepted, comment, mention, release recorded,
+waiting for approval) 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.
+
+Required approvers are asked by name: a run that waits for them sends each one a
+Slack direct message (when their e-mail is in the workspace) with a link into
+review mode, names them in channels that take "waiting for approval" (the Teams
+route), and reminds them once after 24 hours by default. Do not message
+approvers yourself after sharing; tell the person the run is waiting and give
+the review link.
 
 ## Hosted runs
 
@@ -49,8 +56,15 @@ kaloko schedule add --scenario qa/flows/account.yml --env staging --every week -
 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>
+kaloko schedule hook <id>       # URL + secret that start the run after a deploy (secret shown once)
 ```
 
+- Run after a deploy: `kaloko schedule hook <id>` prints a trigger URL and a
+  secret. A deploy (Vercel through a `deployment_status` workflow, Netlify's
+  outgoing webhook with the secret as JWS token) or any CI job calls
+  `curl -X POST <url> -H "Authorization: Bearer <secret>"`. Put the secret in the
+  CI or hosting secrets, never in a file you commit, and do not echo it into logs.
+
 - 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).

package/skills/kaloko/reference/mcp.md

@@ -2,8 +2,9 @@
 
 `https://kaloko.app/mcp` speaks MCP over Streamable HTTP (JSON-RPC 2.0,
 POST only, one message per request). Authenticate with an organization API
-token as `Authorization: Bearer qwk_…`; a read-only token is enough, every
-tool reads. Nothing binary crosses MCP: summaries carry the URLs of
+token as `Authorization: Bearer kal_…`. The server is part of the Team plan
+and up. A read-only token is enough to read; tools that write need a token
+with that scope, as noted below. Nothing binary crosses MCP: summaries carry the URLs of
 screenshots and files, which the same token can fetch over HTTPS.
 
 ## Configure
@@ -20,14 +21,19 @@ file.
 
 ## Tools
 
+List tools (`list_runs`, `list_notifications`, `list_comments`) answer one page: when more match than `limit`, the
+answer's `next` holds a cursor (also as a second text block). Call the tool again with `cursor: <next>` until `next`
+is null. Projects and products come complete, without pages.
+
 | Tool | Use it for |
 |---|---|
-| `list_runs` | published runs, newest first; filters `scenario`, `project`, `verdict`, `author`, `environment`, `branch`, `limit` |
+| `list_runs` | published runs, newest first; filters `scenario`, `project`, `verdict`, `author`, `environment`, `branch`, `limit`; `cursor` for the next page |
 | `get_run_summary` | one run: statuses per step and locale, criteria that need attention with evidence (semantic ones with score and the evaluator's one-sentence `reason` per locale and viewport), regions ignored in pixel diffs and regions seen moving (`ignored_regions`, `unstable_regions`), screenshot URLs, verdict, baseline, canvas URL, open feedback |
 | `get_feedback` | run verdict with note, approved steps, unresolved rejections and comments, failed manual criteria (`run_id`, or `scenario` for its latest run) |
-| `list_notifications` | the token owner's inbox (`unread_only`, `limit`) |
+| `list_notifications` | the token owner's inbox (`unread_only`, `limit`, `cursor`) |
 | `list_projects` | projects of the organization with counts; the slug is the `project` filter of `list_runs` and the value for `project:` in a scenario |
 | `get_criteria_verdicts` | reviewer verdicts on manual or overridden criteria of a run |
+| `get_stack_items` | the pages of a stack step (`run_id`, `step`; filters `status`, `criterion`, text): path, URL, title, status and failing criteria with evidence, screenshot URLs |
 | `get_step_recording` | a step's recording and trace (`run_id`, `step`, `locale`, `viewport`, `trace: true` for the full trace): video URLs, duration, its chapter of a flow recording, failed attempts, the trace summary (failed requests, console errors, slowest request); see [recording.md](recording.md). `get_run_summary` lists trace summaries per step too |
 | `get_review_queue` | what a person still has to decide in a run (`run_id`, or `scenario` / nothing for the newest run): steps in review order with reasons, decisions, approvals carried over unchanged steps with their origin, counts and `review_url` to give the person |
 | `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 |
@@ -36,7 +42,9 @@ file.
 | `list_products` | the products the caller reads: name, modules, the projects it maps that the caller sees, the newest release, published docs (versions, languages), who reads it (and the public link), whether the caller manages it, links to its page, changelog and docs |
 | `get_changelog` | the visual changelog of a product (`product`, `version`, `resolve: true` for the pictures, `limit`): releases newest first with the entry as written and its groups; see [docs.md](docs.md) |
 | `draft_changelog_entry` | what accepted runs since the last release (or `since`) show differently, as a Keep a Changelog draft with before/after step references (`product`, `since`) |
-| `resolve_step_image` | one step reference (`ref` = `kaloko:<scenario>/<step>?…`, `product`, `version`, `locale`, `viewport`) as a signed image URL with its run, how the version was found and canvas links |
+| `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; `video` (mp4, webm, duration_ms) when the step's recording plays (`media=video` / `media=image` in the ref) |
+| `get_docs` | a product's published docs (`product`; without `path` the versions, languages and sidebar; with `path` one page with its Markdown, sections, stale sections and, with `resolve: true`, its pictures) |
+| `docs_check` | what needs attention in the published docs of a version: broken step references, references without an accepted picture, stale sections, missing or outdated translations, release items without a picture |
 | `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 |
@@ -47,10 +55,13 @@ file.
 
 | Tool | Use |
 |---|---|
-| `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 |
+| `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; `limit`, `cursor` |
 | `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_findings` | experimental Clef triage findings of a run (`run_id`): the kind of problem on each screen or in recording frames, with probability, severity and box, and the answers testers gave. Findings never change a verdict |
+| `answer_finding` | answers a finding (`run_id`, `node`, `locale`, `viewport`, `finding`, `kind`, `answer`: right, wrong or comment with the `comment_id` from `add_comment`); scope comment |
+| `get_triage_report` | the organization's Clef numbers of the last 90 days (read-only): findings shown and answered, precision and calibration per kind, findings turned into comments, median hours to the first review with and without findings, triage requests per useful finding. Report them as they are; the go/no-go is a person's |
 | `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 |
@@ -58,14 +69,16 @@ file.
 | `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
+Writes here need a token with the `comment` scope (or full); `add_ignore_region`
+and `run_schedule` need upload or full. Follow *Processing feedback* in
 [collaboration.md](collaboration.md).
 
 Typical loop for an agent that owns a task: `list_runs` with the scenario →
 `get_feedback` for the latest run → fix what was returned → new run with the
 CLI (`kaloko start … share`) → post the canvas URL in the issue. Capturing,
-evaluating and uploading stay in the CLI; MCP reads, and for design drafts also
-publishes versions, sets references and step status, and comments (below).
+evaluating and uploading stay in the CLI; MCP reads, comments, records
+decisions and answers to findings, creates issues, and for design drafts also
+publishes versions and sets references and step status (below).
 
 Errors come back as tool results with `isError: true` (unknown run, expired
 run, missing argument); an invalid token is HTTP 401.

package/skills/kaloko/reference/portable-html.md

@@ -5,7 +5,7 @@ Design steps are live pages. The same files have to work in three places:
 - **on the live origin** of the canvas (`<revision>.kaloko-usercontent.com`): a sandboxed frame with an opaque origin and
   `Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; connect-src 'self'; frame-src 'none';
   worker-src 'none'; form-action 'none'` (no popups, no modals, no service workers);
-- **from disk** (`file://`): the local preview, `kaloko export --design`, and anyone who unzips an export;
+- **from disk** (`file://`): the local preview, `kaloko export design`, and anyone who unzips an export;
 - **in another tool**: the export is the handoff and the way out of Kaloko.
 
 `kaloko design lint` checks a design folder against the rules below; `kaloko sync` runs it first and stops on errors

package/skills/kaloko/reference/recording.md

@@ -72,8 +72,10 @@ missing with the install command for the OS.
 The step detail gets Video next to Screenshot: the poster first, nothing loads
 until played, markers for the start, the capture, actions and failed requests.
 Technical shows the trace; a click on a row moves the video there. Cards play
-the preview on hover. Replay plays the flow recording with its chapters. The
-walkthrough video is in the top bar.
+the preview on hover. Videos play on: after one ends, the next step's video
+starts by itself, and replay with video moves to the next step on its own; a
+step that needs a decision waits, a step without video shows its screenshot for
+three seconds. The walkthrough video is in the top bar.
 
 ## Plans and sharing