kaloko 0.13.0 → 0.15.0

package/skills/kaloko/reference/acceptance.md

@@ -39,28 +39,35 @@ sharpen each purpose and add the criteria the page must really meet.
 ## Check packs
 
 `packs: [seo]` or `packs: [seo, usability]` on a node adds a fixed set of
-criteria (ids `AC1xx` for `seo`, `AC2xx` for `usability`) at load time:
+health checks (ids `HC1xx` for `seo`, `HC2xx` for `usability`; acceptance
+criteria are `AC`, health checks `HC`, and the number is the check's: the
+same check kept in acceptance or adopted is `AC103` for `HC103`) at load time:
 `seo` checks one H1, title and description length, canonical, hreflang for
 every locale, Open Graph, indexing, viewport, `html lang`, overflow and
 console; `usability` checks unlabeled inputs and link texts and asks the
-evaluator questions that fit the step's page type. A node's own criterion with the
-same id wins. Pack criteria are marked `pack` on the canvas and do not count
-as drift in `--coverage`; the plan may still mention them by id. Use packs
-for public pages and landings; task flows keep their own criteria.
+evaluator questions that fit the step's page type. Pack checks are health,
+not acceptance: they are evaluated on every walk but never decide a step's
+verdict (see [evaluation.md#health](evaluation.md#health)). The `design` pack
+always counts for acceptance; `health: { acceptance: [seo] }` on the scenario
+keeps another pack in acceptance, which only the person decides. A node's own
+criterion with the same id wins and counts for acceptance (that is what
+`kaloko health adopt` writes). Pack checks do not count as drift in
+`--coverage`; the plan lists only what the brief asks for. Use packs for
+public pages and landings; task flows keep their own criteria.
 
 Set `page` on every step (or once on the scenario) so the usability pack
 asks the right questions:
 
 | `page` | for | asks |
 | --- | --- | --- |
-| `landing` | public and marketing pages | purpose in the first screen (`AC201`), exactly one primary call to action (`AC202`) |
-| `work` | app screens where people work: overview, canvas, detail, inbox item | the heading says what the screen is for (`AC205`) |
-| `list` | lists and tables: runs, projects, inbox | `AC205`, each item says what it is and how to open it (`AC207`) |
-| `settings` | settings, billing, tokens | `AC205`, each setting says what it changes and how it is saved (`AC208`) |
-| `form` | sign-up, sign-in, a form to fill in | `AC205`, how to send it and what happens next (`AC206`) |
-| `doc` | documentation, guides, terms | `AC201`, headings and short paragraphs (`AC209`) |
-
-Every type also gets `AC203` and `AC204`. Without `page` a step with the
+| `landing` | public and marketing pages | purpose in the first screen (`HC201`), exactly one primary call to action (`HC202`) |
+| `work` | app screens where people work: overview, canvas, detail, inbox item | the heading says what the screen is for (`HC205`) |
+| `list` | lists and tables: runs, projects, inbox | `HC205`, each item says what it is and how to open it (`HC207`) |
+| `settings` | settings, billing, tokens | `HC205`, each setting says what it changes and how it is saved (`HC208`) |
+| `form` | sign-up, sign-in, a form to fill in | `HC205`, how to send it and what happens next (`HC206`) |
+| `doc` | documentation, guides, terms | `HC201`, headings and short paragraphs (`HC209`) |
+
+Every type also gets `HC203` and `HC204`. Without `page` a step with the
 `seo` pack, or any step of a scenario allowed on production, is `landing`;
 everything else is `work`. Do not put `landing` on signed-in screens: "one
 primary call to action" is a marketing rule, and a work screen rightly offers
@@ -78,34 +85,35 @@ When a scenario walks several locales, a text check (`text_matches`,
 reads in one language only (it looks for diacritics and common Czech or
 English words; one plain word such as a brand name is left alone).
 
-- `a11y` (`AC3xx`): images with alt, links and buttons with a name, labelled
+- `a11y` (`HC3xx`): images with alt, links and buttons with a name, labelled
   fields, heading levels not skipped, WCAG AA text contrast, a `main`
-  landmark, unique ids (`AC301`–`AC307`, read from the page). After the
-  screenshot the walk also presses Tab through the page: `AC308` tab order
+  landmark, unique ids (`HC301`–`HC307`, read from the page). After the
+  screenshot the walk also presses Tab through the page: `HC308` tab order
   (hidden focus, big jumps back, positive `tabindex`, controls left out or
-  mouse-only), `AC309` visible focus with at least 3 : 1 contrast (each stop
-  screenshotted focused and unfocused), `AC310` no keyboard trap (a modal
-  dialog may keep focus), `AC311` a skip link or main content within three
-  stops, `AC312` names from Chrome's accessibility tree (what a screen
-  reader announces). `AC313` landmarks (one `main`, labelled repeats) and
-  `AC314` ARIA (unknown roles and attributes, references to missing ids,
+  mouse-only), `HC309` visible focus with at least 3 : 1 contrast (each stop
+  screenshotted focused and unfocused), `HC310` no keyboard trap (a modal
+  dialog may keep focus), `HC311` a skip link or main content within three
+  stops, `HC312` names from Chrome's accessibility tree (what a screen
+  reader announces). `HC313` landmarks (one `main`, labelled repeats) and
+  `HC314` ARIA (unknown roles and attributes, references to missing ids,
   `aria-hidden` over focusable content) are read from the page. The first
   five focus stops are kept as screenshots and the canvas can draw the tab
   order on the capture. The walk only moves focus: nothing is clicked or
   typed, and the page is left unfocused at the top. Stack steps walk the
   keyboard on their first five pages. Still a subset of WCAG 2.2 AA; it
   does not replace an audit with a screen reader.
-- `perf` (`AC4xx`): LCP ≤ 2.5 s, CLS ≤ 0.1, TTFB ≤ 800 ms, page weight ≤ 3 MB,
+- `perf` (`HC4xx`): LCP ≤ 2.5 s, CLS ≤ 0.1, TTFB ≤ 800 ms, page weight ≤ 3 MB,
   measured in this walk's browser since the page load (lab values: the
   machine and network of the walk matter; compare runs, not absolutes).
-  Override a limit with an own criterion of the same id, e.g.
+  Override a limit with an own criterion with the check's number as an AC
+  id (`AC401` for `HC401`), e.g.
   `{ id: AC401, text: LCP within 4 s, check: { type: deterministic, assert: perf_lcp, max: 4000 } }`.
-- `console` (`AC501`): the evaluator reads the step's console errors with its
+- `console` (`HC501`): the evaluator reads the step's console errors with its
   purpose and decides whether they touch what the step accepts (pass: only
   third-party noise; needs review: unsure; fail: relevant). Without errors it
   passes without a call. Keep `no_console_errors` where any error must fail.
 
-- `errors` (`AC6xx`) is for error pages. It checks:
+- `errors` (`HC6xx`) is for error pages. It checks:
   - a real 4xx/5xx status (a "soft 404" answering 200 fails);
   - a link to the home page and navigation or search;
   - no stack trace, SQL error or framework debug page;
@@ -120,7 +128,7 @@ step with `packs: [errors]`:
 - **404:** use `path: /no-such-page-{random}`. `{random}` becomes a new
   token on every walk, so no cache or an accidentally created page makes it
   pass. `kaloko draft` adds this step on its own.
-- **Exact status:** override AC601, for example
+- **Exact status:** override HC601 with your own AC601, for example
   `{ id: AC601, text: Answers 410, check: { type: deterministic, assert: http_status, value: 410 } }`.
   `http_status` also takes `min`/`max`; the default is 200–299.
 - **Every step:** each capture records the document's HTTP status. The
@@ -192,7 +200,8 @@ When the work has a repository and an issue number, make them visible:
 - scenario `id` carries the ticket (`TASK-1273-club-activation`, `WEB-12-checkout`); the CLI derives the issue number from it or from the branch (`feat/1273-…`) and links it to the repository's origin (`acme/shop#1273`);
 - set `issue: { number, repo?, url? }` explicitly when the id or branch cannot carry it (for example a Plane item);
 - the project is the repository name unless `project:` in `kaloko.config.yml` says otherwise; a single flow may sort itself elsewhere with `project: <slug>` in its scenario (optional). Projects are records of the organization: `kaloko projects` or MCP `list_projects` show the slugs to use; admins create them in Settings → Projects or assign a scenario in the overview, which wins over the scenario file;
-- the canvas header, the organization overview and `kaloko feedback` show `repo#number · title`, so name the scenario `title` for humans, not for the ticket.
+- the canvas header, the organization overview and `kaloko feedback` show `repo#number · title`, so name the scenario `title` for humans, not for the ticket;
+- requirement IDs from the team's tracker or QMS go into `refs:` on the scenario, a step or a criterion (`refs: [URS-12, FS-3.4]`, free text, never invented); they flow into the acceptance record and the trace matrix ([evidence.md](evidence.md)).
 
 ## Session and consent
 

package/skills/kaloko/reference/apps.md

@@ -216,7 +216,7 @@ dialog, webview and group.
   - `app_no_truncation`: texts ending in "…";
   - `app_no_crash`: FATAL EXCEPTION or ANR in logcat, a "keeps stopping"
     dialog, or the iOS app no longer running.
-- **Pack `app` (AC7xx):** those four checks, plus a semantic question about
+- **Pack `app` (HC7xx):** those four checks, plus a semantic question about
   the screen's purpose and next action.
 - **Web-only checks** (`no_overflow`, `http_status`, meta, `a11y_contrast`,
   `perf_*`, `url_*`, `style_*`, `js_equals`): these are "not evaluated" on

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.
@@ -352,7 +353,8 @@ Turn on `packs: [design]` (usually `[design, a11y]`) for the steps in the implem
 | AC802 | structure: headings, landmarks, actions and form fields as in the reference |
 | AC803 | tokens: authored colors, fonts, sizes, spacing and radii come from the token set |
 
-Contrast and the other accessibility basics come from the `a11y` pack: `packs: [design, a11y]`.
+The design checks count for acceptance. Contrast and the other accessibility basics come from the `a11y` pack
+(`packs: [design, a11y]`) as health: advisory, reported apart (see [evaluation.md#health](evaluation.md#health)).
 
 `kaloko evaluate` fetches the design reference (of the design branch linked to the git branch, if any) and
 fills the checks. Findings name what differs and the token to use; fix the implementation, not the reference.
@@ -377,7 +379,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/evaluation.md

@@ -68,6 +68,46 @@ evaluators:
 Report the reason with each `needs_review` or failing criterion; when the
 evaluator saw the screenshot, say so.
 
+## Health
+
+The checks of packs (`seo`, `a11y`, `perf`, `usability`, `console`,
+`errors`, `app`) are the run's **health** (CS *kondice*): advisory, stored in
+`node.health` and `summary.health` of `run.json`, never in `criteria`. They
+do not change a step's status, the run verdict, the review queue, carried
+approvals, required approvers, the acceptance record or exit codes. The
+`design` pack and packs listed in `health.acceptance` stay acceptance
+criteria. Runs shared before the split keep their stored verdicts; their pack
+criteria show as health.
+
+- **Check it before you hand over.** `kaloko walk` and `kaloko evaluate`
+  print one health line; `kaloko health` lists the findings by pack with
+  severity (error: people or search engines are shut out; warning: the rest;
+  info: the evaluator was unsure), what is new or fixed since the previous run
+  of the scenario, and a fix for each check. `--json` for the structure,
+  `--remote` (or MCP `get_health`) for a shared run.
+- **Fix what your change can fix**, walk the step again and check that the
+  finding is gone. Leave the rest and say so.
+- **Never hide health.** Do not remove a pack, raise a limit, narrow a
+  selector or add `environments:` to make a finding disappear. A limit or a
+  check that does not fit the project is the person's call; name it in the
+  report.
+- **Ids.** Health checks are `HC<n>` (`home:HC103`), acceptance criteria
+  `AC<n>`. Runs from before 7 Oct 2026 say `AC103` for the health check;
+  read it as `HC103`, and both ids work in commands and MCP.
+- **Adopting is the team's decision.** `kaloko health adopt <step>:<check>
+  [--text "…"]` writes the check into the scenario as an acceptance
+  criterion of the step (`home:HC103` becomes `AC103` with `from: HC103`),
+  so it counts for acceptance from the next walk. Do it only when
+  the person asks. Checks people adopted on the canvas (or through
+  `adopt_health_check`) wait on the service until `kaloko health pull` writes
+  them into the scenario; pulling them is routine, then walk those steps.
+- **Report it apart from the verdicts**: "Health: 2 errors (1 new), 5
+  warnings; fixed HC108 on home". Never present a health finding as a
+  failing criterion, or a clean health as acceptance.
+- `kaloko health --fail-on error` exits 1 on errors; use it in CI only where
+  the team asked for that gate. Hosted runs and CI runs alert on new errors
+  by themselves (inbox, mail, channels, webhook `health.worse`).
+
 ## Triage findings (experimental)
 
 When the organization switched the experiment on, `kaloko evaluate` also asks
@@ -111,7 +151,8 @@ turns them off; they do not count against the hosted allowance.
 
 After `kaloko build`, report: the summary line, each failing or
 `needs_review` criterion with step, locale, viewport and evidence, blocked
-requests if any, and the preview path. Do not claim a criterion passed when
+requests if any, the health counts (apart from the verdicts), and the preview
+path. Do not claim a criterion passed when
 it was not evaluated.
 
 `needs_review` is not a failure: look at the screenshot and state your

package/skills/kaloko/reference/evidence.md

@@ -0,0 +1,80 @@
+# Evidence for your own documentation (regulated work)
+
+Use this when a team's own repository turns Kaloko runs into its documents: test protocols, reports, trace
+matrices, release summaries for a quality system. Kaloko provides the evidence and a way to check it; the team's
+own templates and skills write the documents. Kaloko never formats anything for a particular QMS, and you do not put
+the team's SOP structure into Kaloko.
+
+The background for people (what a record proves, the two signing paths, known gaps) is in Kaloko's help, page
+*Kaloko in regulated work (GxP)*. Evidence is a Business feature.
+
+## The contract
+
+Everything below is `qawalk.evidence.v1` (`schemas/evidence.v1.json` in the `kaloko` package, every field
+described). Within v1 fields are only added; read the fields you need and ignore the rest.
+
+- `acceptance`: `none`, `accepted` or `returned`. Write your document from this field, never from the presence of
+  others.
+- `signing`: `in_kaloko` when a signature made in Kaloko stands, `none` otherwise. With `none` the approval, if any,
+  is signed elsewhere; your document says so ("executed in Kaloko; approval recorded in <your eQMS>").
+- `record.sha256` and `record.kind` (`acceptance` or `execution`): the signed record the evidence came from. Put the
+  hash into your document so a reader can tie it to the package.
+- `scenario` (`version`, `file`, `sha256`, `refs`), `environment`, `git`, `tools` (CLI, Node.js, OS, browsers,
+  service version).
+- `steps[].criteria[]`: the criterion text as walked, `refs`, and `results[]` per locale and viewport with
+  `assessed_by` (`person`, `deterministic`, `ai`, `none`) and `assessor` (an e-mail or a model id). `advisory: true`
+  means an AI result no person decided: never present it as a person's verdict.
+- `steps[].decision`, `verdict`, `approvals`: people's decisions apart from tokens' and agents'
+  (`counts_as_person`).
+- `signatures[]` (name, e-mail, `signed_at`, `time_zone`, `local_time`, `meaning`, `auth`, `withdrawn`) and
+  `decision_changes[]` with reasons.
+- `audit[]`: the run's audit trail; `trace[]`: the trace matrix, one row per requirement, criterion, step, locale and
+  viewport (columns in `TRACE_COLUMNS` order, the same as `trace.csv`).
+- A release (`kind: release`) has `runs[]` (each a run evidence), `missing[]` with reasons and one `trace[]`.
+
+## Getting it
+
+```bash
+npx kaloko evidence <run-id> --json > evidence.json            # one run, any shared run
+npx kaloko evidence --release 2.4.0 --product lims --json > release.json
+npx kaloko evidence <run-id> --csv > trace.csv                 # the trace matrix only
+npx kaloko signoff <run-id> --package --out evidence/          # the signed zip, checked on download
+npx kaloko signoff --verify evidence/kaloko-evidence-<run-id>.zip   # check it again later, no token needed
+```
+
+Over the API with a read token: `GET /api/v1/orgs/<org>/runs/<id>/evidence`, `…/evidence.zip`, `…/trace.csv`,
+`…/audit.csv`, and `GET /api/v1/orgs/<org>/evidence?product=<p>&version=<v>`. Over MCP: `get_evidence` with `run_id`, or
+`product` and `version`.
+
+## When it is ready
+
+An organization admin adds a webhook with the event `evidence.ready` (Settings → Integrations → Webhooks). It fires
+when a run is shared, accepted or returned, and when a release is recorded or updated. It is signed like every Kaloko
+webhook (`Kaloko-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<body>">`); check the signature and the age of `t`
+before you trust it. The body:
+
+```json
+{ "id": "evt_…", "type": "evidence.ready", "created_at": "2026-10-07T10:00:00.000Z", "org": "acme",
+  "data": { "kind": "run", "reason": "accepted", "run": { "id": "2026-10-07-batch-x1y2z3", "scenario": "BATCH", "environment": "validation", "project": "lims", "verdict": "accepted" },
+            "acceptance": "accepted", "signing": "none", "schema": "qawalk.evidence.v1",
+            "evidence_url": "https://kaloko.app/api/v1/orgs/acme/runs/…/evidence", "package_url": "…/evidence.zip", "trace_csv_url": "…/trace.csv" } }
+```
+
+The URLs need a token (`Authorization: Bearer …`); the webhook never carries the evidence itself.
+
+A neutral client-side job, for example a small service or a CI job triggered by the webhook:
+
+1. Check `Kaloko-Signature` with the webhook's secret; drop events older than five minutes.
+2. Download `package_url` with a read token into your own storage.
+3. Run `npx kaloko signoff --verify <zip>`; stop and alert on any failure.
+4. Read `evidence.json` from the zip and hand it to your generator with your templates.
+5. Store the generated document next to the package and the record's SHA-256; your eQMS takes it from there.
+
+## Rules for an agent
+
+- Never accept, approve or sign for a person. Tokens and agents cannot sign; where an organization signs in Kaloko,
+  only a person does, in the app.
+- Never present `advisory` results as decisions, and never drop the AI model name from a result.
+- Do not turn the signature policy on or off; that is an admin's decision in Settings → Security.
+- Add `refs:` to scenarios, steps and criteria when the team gives you requirement IDs; do not invent them.
+- Keep the package as you got it. To change anything, generate a new document; the package stays the evidence.

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, health got worse) 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).
@@ -58,6 +72,11 @@ kaloko schedule pause|resume|remove <id>
   script that only calls `page.goto`). Steps that click or type are left out and
   named in the answer. Criteria decided: `exists`, `absent`, `count`, `text_*`,
   `attr_*`, `title_matches`, `meta_matches`; the rest shows "not evaluated".
+- Health alerts: a hosted run (and a run shared from CI) compares its health
+  with the previous run of the scenario and alerts the followers, the channels
+  and the `health.worse` webhook on a new error-level finding. Each schedule
+  sets it to `error` (default), `warning` or `off` on kaloko.app or with
+  `kaloko schedule add --health-alert`; changing it is the person's call.
 - Does not work for: native apps, local or private addresses (localhost, IPs,
   `.local`), header credentials, base URLs per locale.
 - For those, or for the full walk on a schedule, write a GitHub Actions

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,26 +42,30 @@ 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 |
 | `search_screens` | the screen library: newest screenshot of every step across the organization's flows (`q` words matched against titles, ids, paths, URLs, page title and H1; `project`, `product`, `module`, `scenario`, `locale`, `viewport`, `device`, `status`, `environment`; `source: design` or `all` for design versions; `group: none` for every locale and viewport; `cursor` from `next`), each with a signed image and the canvas link |
+| `get_health` | the advisory health of a run (`run_id`), the newest run of a scenario (`scenario`) or the trend of a project (`project`): findings by severity, pack and step with evidence and a fix, and what is new or fixed since the previous run; never a verdict, see [evaluation.md#health](evaluation.md#health) |
+| `adopt_health_check` | turns a health check into an acceptance criterion of the scenario (`run_id`, `step`, `check` such as `HC103`, `text` to reword it; it becomes `AC103` with `from: HC103`); Developer / Tester role. Only when the person asks; `kaloko health pull` then writes it into the scenario file |
 | `get_affected_steps` | which steps of a scenario changed files reach, with the reason per step (`scenario`, `changed_files`, `run_id`, `upstream`); route files are matched against the step paths and URLs of the newest run. Imports and `affects:` globs need the repository: `kaloko affected` follows them |
 
 ## Comment tools
 
 | 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 |
+| `get_evidence` | the evidence of a run (any shared run) or a release (Business, `qawalk.evidence.v1`): acceptance and signing state, criteria as walked with `refs`, who assessed each result (AI advisory), screenshots with SHA-256, decisions, signatures, audit trail, trace matrix ([evidence.md](evidence.md)) |
 | `resolve_comment` | close a thread with a `note` that says what changed (it becomes the last reply) |
 | `reopen_comment`, `edit_comment`, `delete_comment` | reopen; edit or delete your own comment |
 | `create_issue` | a Jira or Linear issue from a step (`run_id`, `step`, `to`: jira or linear, optional `criterion`, `title`, `note`, `locale`, `viewport`, `target`): screenshot, criterion, notes and a link back; the step's thread resolves when the issue is done. Developer / Tester, scope comment; see [integrations.md](integrations.md) |

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

@@ -29,7 +29,7 @@ step script only to prepare each page, for example to dismiss a dialog
   kind: stack
   title: Magazine articles
   purpose: Every article reads well and is findable.
-  packs: [seo]                              # the pack criteria apply to every page
+  packs: [seo]                              # health checks of every page (advisory)
   items:
     sitemap: /sitemap.xml                   # or urls / file / crawl / script (exactly one)
     match: '^/clanky/'                      # regex on the path with its query; exclude: '…' drops pages