kaloko 0.13.0 → 0.14.0

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,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.13.0",
+  "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",

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

@@ -83,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
 

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
 
@@ -67,11 +69,36 @@ maps routes as well as a laptop with earlier runs. See
 
 ## Exit codes
 
-Every command exits with `0` when it is done, `1` when checks found problems
-or the command failed, and `2` on a usage error such as an unknown command or
-option or a missing argument. A CI step can tell a broken workflow line (2)
-from a failing check (1). `kaloko help <command>` or `kaloko <command> --help`
-shows the options of one command.
+| 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
 

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):
 
 ```
@@ -58,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,7 +2,7 @@
 
 `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_…`. The server is part of the Team plan
+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.
@@ -21,12 +21,16 @@ 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 |
@@ -38,7 +42,7 @@ 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) |
@@ -51,12 +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 |

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