kaloko 0.4.8 → 0.4.10

package/README.md

@@ -27,8 +27,11 @@ npx kaloko doctor
 ```
 
 `init` creates `kaloko.config.yml` and copies the `kaloko` skill to
-`.claude/skills/kaloko` (Claude Code) or `skills/kaloko` (Codex). Run it again
-after `npm update kaloko` to refresh the skill.
+`.claude/skills/kaloko` (Claude Code) or `skills/kaloko` (Codex). It reads the
+project first: the framework (Next.js, Nuxt, SvelteKit, Remix, Astro, Rails and
+others), the dev server's command and URL, the locales of the i18n config and
+the main routes, and drafts `qa/flows/main-pages.yml` so the first walk works
+without editing. Run it again after `npm update kaloko` to refresh the skill.
 
 ## Then ask your agent
 
@@ -61,7 +64,65 @@ npx kaloko preview                    # local canvas
 npx kaloko share --pr                 # upload to kaloko.app, comment on the PR
 ```
 
-`npx kaloko help` lists every command. When something does not work (Chrome,
+After a fix, walk only what the change reaches: `npx kaloko affected` explains
+which steps the changed files touch (routes, imports, `affects:` globs in the
+scenario), and `npx kaloko walk --affected` walks them. Several locales walk at
+once with `--concurrency 3`. When a step's selector no longer exists, the walk
+proposes one from the page and prints the patch; `--heal` applies it once the
+step passes.
+
+`npx kaloko help` lists every command.
+
+## Pull request previews in CI
+
+```bash
+npx kaloko ci github      # or: npx kaloko ci gitlab
+```
+
+writes a workflow that waits for the pull request's preview deployment
+(Vercel, Netlify, Cloudflare Pages, any review app), walks the steps the change
+affects and puts one comment per scenario on the pull request. Add a
+`KALOKO_TOKEN` secret (tester role) and commit it. In short, the GitHub
+workflow does this:
+
+```yaml
+on:
+  deployment_status:
+jobs:
+  walk:
+    if: github.event.deployment_status.state == 'success'
+    runs-on: ubuntu-latest
+    env:
+      KALOKO_TOKEN: ${{ secrets.KALOKO_TOKEN }}
+      GH_TOKEN: ${{ github.token }}
+      KALOKO_BROWSER_CHANNEL: chromium
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npm ci
+      - run: npx kaloko browser install --with-deps
+      - run: npx kaloko ci preview-url --wait 600 --github-env
+      - run: |
+          npx kaloko start --scenario qa/flows/checkout.yml --env preview
+          npx kaloko walk --ephemeral --affected
+          npx kaloko share --pr
+```
+
+Uploads go by content hash: captures that did not change since an earlier run
+are not sent again, and an interrupted `share` picks up where it stopped.
+
+## Screenshots you already have
+
+```bash
+npx kaloko import playwright-report/        # or test-results/, a trace.zip, results.json
+npx kaloko import walkthrough/ --adhoc      # a Cursor or Antigravity walkthrough, a folder of screenshots
+```
+
+lays screenshots, Playwright reports and traces out as a run: matched to the
+scenario's steps (by step id in `steps.json`, URL or title), or as an ad-hoc
+flow when there is no scenario. Build and share it like any run. When something does not work (Chrome,
 token, environment URL, evaluator key), `npx kaloko doctor` says what to fix.
 
 ## Review only what changed
@@ -81,6 +142,15 @@ what still waits for a person, so it can pass the link on. Agents never
 approve for people: their decisions are marked and do not count as a
 person's.
 
+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.
+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`
+find the clocks, ads and carousels worth ignoring.
+
 ## Design (Kaloko Design)
 
 Design the screens of a flow as live HTML with your own agent and skills, in the same scenario that development
@@ -98,6 +168,17 @@ npx kaloko share --name "Checkout v2"     # a version of the whole flow
 npx kaloko reference --design --version 2 # after the team accepted it
 ```
 
+Developers and their agents build from what was approved. *Dev mode* (`D` in the step detail) shows each
+element's box, sizes and distances, its colors, type and spacing with the token every value comes from (or a
+warning when it is not a token), contrast against WCAG AA, the `:hover`, `:focus`, `:active` and disabled states,
+and its images. The same data is the step spec an agent reads, and `kaloko drift` checks the implementation
+against it:
+
+```bash
+npx kaloko spec payment                   # elements, styles → tokens, states (also MCP get_step_spec)
+npx kaloko walk && npx kaloko drift       # expected token vs actual value per element; exit 1 while it differs
+```
+
 On the canvas, *Prototype* (or `P`) presents the steps full screen as live pages: click through links between
 steps, switch the device, walk with the arrow keys, and share a link that opens straight into a step. The rules
 for pages that work everywhere are in `skills/kaloko/reference/portable-html.md`.
@@ -141,13 +222,19 @@ captured HTML, page text and console output.
 - **Service and evaluator**: `KALOKO_TOKEN` for `share`, `feedback`, `review`, `inbox` and clean-up (`runs`, `trash`, `prune`, `keep`, `archive`)
   (`npx kaloko login` approves one in the browser and saves it to `~/.config/kaloko/.env`, or create it in your
   organization's settings); `TYPESAFE_API_KEY` for the
-  semantic evaluator (optional). Both names can be changed in the config.
+  semantic evaluator and `ANTHROPIC_API_KEY` for the vision evaluator (both
+  optional; without them Kaloko evaluates on your plan's allowance). The names
+  can be changed in the config.
 
 `npx kaloko doctor` checks that every variable the config names is set and that
 each environment lets you in.
 
 Set `browser.channel: chrome` to use an installed Chrome, or run
-`npx playwright install chromium`.
+`npx kaloko browser install` for the Chromium of kaloko's Playwright
+(`KALOKO_BROWSER_CHANNEL=chromium` then uses it, which is how CI runs).
+In CI, `KALOKO_PREVIEW_URL`, `KALOKO_PR` and `KALOKO_BASE` come from
+`npx kaloko ci preview-url`; `KALOKO_GITLAB_TOKEN` lets `share --pr` comment on
+GitLab merge requests.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "description": "See what your AI agents built: every screen, language and device walked, assessed and approved on one canvas.",
   "keywords": [
     "qa",

package/schemas/config.v1.json

@@ -45,9 +45,42 @@
             "signals": { "type": "boolean", "default": true, "description": "Quick signals on every screen (purpose met, expected language, looks broken); never change verdicts." },
             "concurrency": { "type": "integer", "minimum": 1, "maximum": 16, "default": 6, "description": "Evaluator requests in flight at once." }
           }
+        },
+        "vision": {
+          "description": "Second, vision-capable evaluator (#17): sees the screenshot (a crop for scoped criteria) and answers with a probability and a one-sentence reason. Asked only for criteria with vision: true and for text answers in the uncertain band; false turns it off.",
+          "oneOf": [
+            { "const": false },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "provider": { "enum": ["anthropic"], "default": "anthropic" },
+                "model": { "type": "string", "default": "claude-opus-5-5", "description": "Model id of the provider (Anthropic Messages API with image input)." },
+                "api_key_env": { "type": "string", "default": "ANTHROPIC_API_KEY" },
+                "base_url": { "type": "string", "default": "https://api.anthropic.com" },
+                "when": { "enum": ["uncertain", "flagged", "always", "off"], "default": "uncertain", "description": "flagged: only criteria with vision: true; uncertain: those plus text answers in the uncertain band; always: every semantic criterion (most expensive)." },
+                "uncertain": { "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 1 }, "minItems": 2, "maxItems": 2, "default": [0.15, 0.85], "description": "Text scores strictly between these go to the vision evaluator." },
+                "max_calls": { "type": "integer", "minimum": 0, "default": 40, "description": "Vision requests per evaluation (uncached); the rest stay with the text answer." },
+                "max_width": { "type": "integer", "minimum": 320, "maximum": 1568, "default": 1000, "description": "Images are scaled down to this width (px)." },
+                "tile_height": { "type": "integer", "minimum": 400, "maximum": 1568, "default": 1400, "description": "A full page is cut into tiles of this height." },
+                "max_tiles": { "type": "integer", "minimum": 1, "maximum": 4, "default": 2, "description": "Tiles of a full page sent at most (from the top); scoped criteria get a crop instead." },
+                "effort": { "enum": ["low", "medium", "high"], "default": "low" },
+                "reason_language": { "type": "string", "default": "en", "description": "Language of the one-sentence reasons (en, cs, …)." },
+                "hosted": { "type": "boolean", "default": true, "description": "Without a local key, ask through the organization's service (counts against the monthly allowance; one vision question counts as 5)." },
+                "concurrency": { "type": "integer", "minimum": 1, "maximum": 8, "default": 3 }
+              }
+            }
+          ]
         }
       }
     },
+    "walk": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "concurrency": { "type": "integer", "minimum": 1, "maximum": 16, "description": "Locales walked at the same time, each in its own browser context (kaloko walk --concurrency). Default: by CPU in an own browser, one at a time on the shared browser." }
+      }
+    },
     "share": {
       "type": "object",
       "additionalProperties": false,

package/schemas/scenario.v1.json

@@ -243,6 +243,13 @@
           "type": "string",
           "description": "Key from `sessions`; which person performs this step."
         },
+        "affects": {
+          "oneOf": [
+            { "const": "always" },
+            { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
+          ],
+          "description": "For `kaloko walk --affected`: globs of repository files (relative to the config) that shape this step, next to the routes and imports Kaloko finds itself; `always` walks the step on every affected walk (sign-in, consent)."
+        },
         "packs": {
           "type": "array",
           "items": {
@@ -262,6 +269,11 @@
         "capture": {
           "$ref": "#/$defs/capture"
         },
+        "ignore": {
+          "type": "array",
+          "description": "Regions left out of pixel comparisons (clocks, ads, carousels): a selector, or a rectangle in page pixels of one viewport. kaloko stability suggests them.",
+          "items": { "$ref": "#/$defs/ignoreRegion" }
+        },
         "items": {
           "type": "object",
           "additionalProperties": false,
@@ -500,6 +512,13 @@
             "a11y_contrast",
             "a11y_main",
             "a11y_unique_ids",
+            "a11y_focus_order",
+            "a11y_focus_visible",
+            "a11y_keyboard_trap",
+            "a11y_skip_link",
+            "a11y_ax_names",
+            "a11y_landmarks",
+            "a11y_aria",
             "perf_lcp",
             "perf_cls",
             "perf_ttfb",
@@ -588,6 +607,10 @@
             "console"
           ],
           "description": "console: the evaluator reads the captured console errors with the step purpose (triage) instead of the page"
+        },
+        "vision": {
+          "type": "boolean",
+          "description": "Also show the evaluator the screenshot (a crop of scope when set): layout, imagery, brand. Needs a vision evaluator (evaluators.vision)."
         }
       }
     },
@@ -632,6 +655,22 @@
         }
       }
     },
+    "ignoreRegion": {
+      "type": "object",
+      "additionalProperties": false,
+      "oneOf": [
+        { "required": ["selector"] },
+        { "required": ["rect", "viewport"] }
+      ],
+      "properties": {
+        "selector": { "type": "string", "minLength": 1, "description": "CSS selector; every visible match is ignored." },
+        "rect": { "type": "array", "items": { "type": "number", "minimum": 0 }, "minItems": 4, "maxItems": 4, "description": "[x, y, width, height] in CSS pixels of the page." },
+        "viewport": { "type": "string", "description": "The viewport a rect belongs to." },
+        "viewports": { "type": "array", "items": { "type": "string" }, "description": "Only in these viewports (selector)." },
+        "locales": { "type": "array", "items": { "type": "string" }, "description": "Only in these locales." },
+        "note": { "type": "string" }
+      }
+    },
     "capture": {
       "type": "object",
       "additionalProperties": false,

package/schemas/spec.v1.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qawalk.com/schemas/spec.v1.json",
+  "title": "qawalk.spec.v1",
+  "description": "The step spec (#42 Dev mode): what to build for one step as it was approved. Written by the in-page engine src/lib/devspec.mjs at capture (steps/<step>/<locale>/<viewport>.spec.json, and the capture record of a design revision); the canvas Dev mode runs the same engine on the live page. Served by GET …/scenarios/<id>/steps/<step>/spec, MCP get_step_spec and kaloko spec. Elements are listed in page order; a style lists only what differs from what the element inherits (page, then the parent element).",
+  "type": "object",
+  "required": ["schema", "elements"],
+  "$defs": {
+    "value": {
+      "type": "object",
+      "description": "A computed value (colors as #rrggbb[aa], lengths in px) and the token it maps to. token: the DTCG path (several, space-separated, for a shorthand such as padding; 0 for a zero side); null when the set has tokens of that kind but none fits and none is near. nearest: the closest token when the value is not one. mode: the mode whose value it is (light, dark, …). hard: the stylesheet typed the raw value although the token exists. var: the custom property the author used when it names no token.",
+      "required": ["value"],
+      "properties": {
+        "value": { "type": "string" },
+        "token": { "type": ["string", "null"] },
+        "nearest": { "type": "string" },
+        "mode": { "type": "string" },
+        "hard": { "type": "boolean" },
+        "var": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "styles": {
+      "type": "object",
+      "description": "CSS property → value: color, background-color, border-color, font-family, font-size, font-weight, line-height, letter-spacing, padding, gap, row-gap, column-gap, border-width, border-radius, box-shadow, opacity, display and flex or grid properties.",
+      "additionalProperties": { "$ref": "#/$defs/value" }
+    }
+  },
+  "properties": {
+    "schema": { "const": "qawalk.spec.v1" },
+    "title": { "type": "string" },
+    "lang": { "type": ["string", "null"] },
+    "viewport": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 },
+    "size": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Document width and height." },
+    "tokens": { "type": ["object", "null"], "description": "The token set the values were mapped with (the step's tokens.json); null without one.", "properties": { "count": { "type": "integer" }, "modes": { "type": "array", "items": { "type": "string" } } } },
+    "page": { "$ref": "#/$defs/styles", "description": "Typography and text color of the page (body), inherited by every element that does not say otherwise." },
+    "elements": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["i", "parent", "tag", "sel", "styles"],
+        "properties": {
+          "i": { "type": "integer" },
+          "parent": { "type": "integer", "description": "Index of the nearest listed ancestor, -1 at the top." },
+          "tag": { "type": "string" },
+          "role": { "type": ["string", "null"], "description": "ARIA role, explicit or implicit (button, link, heading, main, textbox, …)." },
+          "name": { "type": ["string", "null"], "description": "Accessible name or own text (at most 80 characters)." },
+          "sel": { "type": "string", "description": "A CSS selector of the element in the design page (ids, data-testid and classes first)." },
+          "box": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4, "description": "x, y, width, height in CSS px of the page." },
+          "styles": { "$ref": "#/$defs/styles" },
+          "contrast": { "type": "object", "properties": { "ratio": { "type": "number" }, "aa": { "type": "boolean" } } },
+          "states": { "type": "object", "description": "hover, focus, active, disabled → the styles that change in that state (the page's rules forced on the element).", "additionalProperties": { "$ref": "#/$defs/styles" } },
+          "asset": { "type": "object", "properties": { "kind": { "enum": ["img", "svg"] }, "src": { "type": "string" }, "size": { "type": "array" }, "alt": { "type": ["string", "null"] } } }
+        }
+      }
+    },
+    "used": { "type": "object", "description": "Token path → number of values that use it.", "additionalProperties": { "type": "integer" } },
+    "off": { "type": "array", "description": "Values outside the token set, most frequent first.", "items": { "type": "object", "properties": { "prop": { "type": "string" }, "value": { "type": "string" }, "count": { "type": "integer" }, "nearest": { "type": ["string", "null"] }, "sel": { "type": "string" } } } }
+  }
+}

package/skills/kaloko/SKILL.md

@@ -11,7 +11,9 @@ description: >
   reviewer rejected on a canvas, what is waiting in the Kaloko inbox, or how
   to report a run in an issue, and when designing screens of a flow in a
   design environment (live HTML steps, drafts, versions, the design
-  reference, checking implementation against it).
+  reference, checking implementation against it), and when implementing a
+  screen that has an approved design (read the step spec, build with its
+  tokens, check drift).
 ---
 
 # Kaloko
@@ -32,6 +34,10 @@ the canvas, storage and collaboration are the service.
   for them (`kaloko share` prints it; `kaloko review` repeats it), and you
   read `kaloko feedback` and `kaloko inbox` before continuing on that task.
 - Changes to intent are written back to `ACCEPTANCE.md` (change log row).
+- When you implemented a step from an approved design: you read its spec
+  (`kaloko spec <step>`), walked the implementation with `packs: [design]`,
+  and `kaloko drift` is clean or the PR names each difference left for a
+  person to decide.
 - On a design environment: the folder follows the bundle rules and
   `kaloko design lint` shows no error, `kaloko walk` and `kaloko sync` ran,
   `kaloko status` shows no conflict, and you read the draft's feedback; a
@@ -42,7 +48,9 @@ the canvas, storage and collaboration are the service.
 Start the shared browser, walk a scenario on a non-production environment,
 create test data there (users, roles, carts), capture screens and e-mails,
 evaluate, build the preview, and fix scenario mechanics (selectors, scripts)
-that do not change what is being accepted. On a design environment: change
+that do not change what is being accepted, including applying a selector
+proposal with `kaloko walk --heal` when it names the same element. Walk only
+the steps a change reaches (`--affected`) and import screenshots into a run. On a design environment: change
 the design folder, walk, and sync the draft (including taking others' steps
 with `--theirs`). Move to the trash runs you uploaded in this session that
 were superseded before anyone looked at them (debug rounds: no comments, no
@@ -50,7 +58,8 @@ verdict), and run `kaloko prune` without `--yes` to see what a clean-up would do
 
 ## Ask first
 
-Changing acceptance criteria or scope, any production run, uploading with
+Changing acceptance criteria or scope, any production run, writing or
+replacing a CI workflow (`kaloko ci github|gitlab`), uploading with
 `kaloko share` (on a design environment: publishing a version), setting a
 design reference or baseline, merging a design branch, keeping your version of
 a step in a sync conflict (`--mine`), turning on `html_view`, a real clean-up
@@ -77,6 +86,15 @@ they can do; never write secrets into the config, a scenario or a script.
   [reference/stacks.md](reference/stacks.md)
 - Choosing playwright, agent or manual per step, and driving the shared
   browser with your capabilities: [reference/execution.md](reference/execution.md)
+- Evaluation, thresholds, the vision evaluator and its reasons, reading
+  results: [reference/evaluation.md](reference/evaluation.md)
+  browser with your capabilities, walking only the steps a change reaches
+  (`--affected`), several locales at once, and selectors that moved
+  (`--heal`): [reference/execution.md](reference/execution.md)
+- 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)
+- CI: a workflow that walks each pull request's preview deployment and
+  comments on it (`kaloko ci github|gitlab`): [reference/ci.md](reference/ci.md)
 - Evaluation, JEV thresholds and reading results: [reference/evaluation.md](reference/evaluation.md)
 - Environments, access (gates, accounts, sign-in), e-mails, readonly and
   production rules, and what is yours to arrange for the project's stack:
@@ -94,6 +112,9 @@ they can do; never write secrets into the config, a scenario or a script.
   references, handoff, tokens, the design pack, canvas edits, branches, HTML
   view, presenting the prototype, exports, bringing your own design skill):
   [reference/design.md](reference/design.md)
+- Implementing a screen from the approved design: read the step spec, build
+  with its tokens, walk, check drift, fix:
+  [reference/design.md#implement-from-the-approved-design](reference/design.md#implement-from-the-approved-design)
 - Writing design pages that work on the live step, from disk and in other
   tools (relative URLs, no CDNs, state in the URL, deterministic content,
   links between steps; what `kaloko design lint` checks):

package/skills/kaloko/reference/acceptance.md

@@ -20,6 +20,16 @@ unclear, ask one focused question instead of guessing.
 When intent changes, update `ACCEPTANCE.md` first, add a change-log row with
 date and commit, bump `version` in the scenario, then adjust the scenario.
 
+In a project without scenarios, `kaloko init` already drafted
+`qa/flows/main-pages.yml` from the route files: one screen per main route in
+the locales of the i18n config, with the dev server's URL as `local`. It walks
+as it is; sharpen the purposes and criteria and add the flows that matter.
+
+Screenshots an agent or a test tool already took (a Cursor or Antigravity
+walkthrough, a Playwright report or trace) can start a scenario too:
+`kaloko import <folder> --adhoc` writes one manual step per screen; see
+[import.md](import.md).
+
 For public pages of a site (landings, marketing, documentation) start from a
 draft: `npx kaloko draft https://example.com/ https://example.com/pricing`
 fetches the pages and writes a read-only production scenario and its plan
@@ -40,8 +50,21 @@ for public pages and landings; task flows keep their own criteria.
 
 - `a11y` (`AC3xx`): images with alt, links and buttons with a name, labelled
   fields, heading levels not skipped, WCAG AA text contrast, a `main`
-  landmark, unique ids. A subset of WCAG 2.2 AA checked in the page; it does
-  not replace an audit with a screen reader.
+  landmark, unique ids (`AC301`–`AC307`, read from the page). After the
+  screenshot the walk also presses Tab through the page: `AC308` 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,
+  `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,
   measured in this walk's browser since the page load (lab values: the
   machine and network of the walk matter; compare runs, not absolutes).
@@ -120,6 +143,12 @@ criteria whose verdict differs between runs on the same commit as flaky;
 treat a flaky criterion as a selector or timing problem to fix in the
 scenario, not as a verdict.
 
+When a step is shaped by files no route reaches (a payment library, a shared
+price component), name them on the step with `affects: [lib/payments/**]`, so
+`kaloko walk --affected` walks it when they change; `affects: always` marks
+steps every walk needs (sign-in, consent). See
+[execution.md](execution.md#only-what-changed).
+
 ## Naming and linkage
 
 When the work has a repository and an issue number, make them visible:
@@ -227,3 +256,22 @@ skips a session's nodes there. The canvas shows a chip with the person on
 every step, groups the step list by person and draws hand-offs between
 people as dashed arrows. Sessions run one after another, never in parallel,
 and never share cookies.
+
+## Ignore regions
+
+Clocks, ads, carousels and "3 minutes ago" change on every capture and make
+pixel diffs noisy. List them on the step and both the canvas diff and the
+design pixel check (`AC801`) leave them out:
+
+```yaml
+- id: home
+  ignore:
+    - { selector: "#clock" }                       # every visible match
+    - { selector: ".ad-slot", viewports: [desktop] }
+    - { rect: [0, 620, 1280, 240], viewport: desktop } # page pixels of one viewport
+```
+
+Do not guess them: `kaloko walk --stability 3` notes what moves while the
+page sits still, and `kaloko stability` compares the step with earlier runs
+and writes suggestions (see [execution.md](execution.md)). Ignore only noise;
+a region that matters to a criterion stays in.

package/skills/kaloko/reference/ci.md

@@ -0,0 +1,70 @@
+# CI and pull request previews
+
+Kaloko runs in CI with the same commands as on a laptop. `kaloko ci` writes the
+workflow; you only add a token. Writing or replacing a CI workflow changes the
+repository's pipeline: ask the person first.
+
+```bash
+kaloko ci github [--scenario qa/flows/checkout.yml,qa/flows/signup.yml]   # .github/workflows/kaloko.yml
+kaloko ci gitlab                                                       # kaloko.gitlab-ci.yml (include it)
+kaloko ci github --print                                               # show it, write nothing
+```
+
+What the generated workflow does on every preview deployment of a pull
+request (Vercel, Netlify and Cloudflare Pages report their previews as GitHub
+deployments; `--trigger pull_request` runs on every push instead and waits for
+the deployment):
+
+1. installs the project (`npm ci`, or pnpm, yarn, bun by the lockfile) and the
+   Chromium of kaloko's Playwright (`kaloko browser install --with-deps`);
+   `KALOKO_BROWSER_CHANNEL=chromium` makes the run use it, so no separate CI
+   config is needed;
+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`,
+   `walk --ephemeral --affected` and `share --pr` (one comment per scenario,
+   updated on later pushes).
+
+`kaloko ci` also adds the `preview` environment to `kaloko.config.yml` with
+`base_url: ${KALOKO_PREVIEW_URL}`. Scenarios that list `environments:` must
+include `preview`, or `start` refuses them; the command says which.
+
+## Secrets
+
+- `KALOKO_TOKEN`: a token with the tester role and the upload scope (Settings →
+  API tokens; on Enterprise a service account's token, which no person owns).
+- `TYPESAFE_API_KEY` only when semantic criteria should use your own evaluator
+  key instead of the organization's allowance.
+- Vercel deployment protection: a `VERCEL_AUTOMATION_BYPASS_SECRET` secret and
+  the commented `access.headers` block of the preview environment.
+- GitLab: `KALOKO_GITLAB_TOKEN` (project access token, `api` scope) for the
+  merge request note; set `KALOKO_PREVIEW_URL` in the job when the review app
+  URL is known (`https://$CI_COMMIT_REF_SLUG.review.example.com`), or rely on
+  `CI_ENVIRONMENT_URL`.
+
+## Where the preview URL comes from
+
+`kaloko ci preview-url` takes the first of: `KALOKO_PREVIEW_URL`; the
+`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.
+
+## Affected steps in CI
+
+`walk --affected` needs the history: check out with `fetch-depth: 0` (GitHub)
+or `GIT_DEPTH: "0"` (GitLab). The base is `--base`, else `KALOKO_BASE`,
+`GITHUB_BASE_REF`, the merge request target, then `origin/main`. URLs captured
+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).
+
+## Done means
+
+The workflow file and the config change are committed after the person agreed,
+the secret is named for the person to add, and you report the first run's PR
+comment or why it did not appear (no preview deployment, missing token).

package/skills/kaloko/reference/collaboration.md

@@ -12,7 +12,9 @@ loop teams use:
    request and `gh` is signed in, `kaloko share --pr` posts one comment per
    scenario on it (summary line, canvas link, criteria that need attention
    with evidence) and updates that same comment on every later run, so the
-   PR never fills up with Kaloko noise. Otherwise write the comment yourself:
+   PR never fills up with Kaloko noise. In CI `KALOKO_PR` names the pull
+   request of a detached checkout, and on GitLab merge requests the comment is a
+   note on the MR (`KALOKO_GITLAB_TOKEN`). Otherwise write the comment yourself:
    what was tested (scenario, environment, locales), the summary line
    (`n/m steps passed`), every failing or `needs_review` criterion with
    evidence, and the canvas URL. Reviewers accept, return or comment on the
@@ -255,6 +257,12 @@ Everything above is available over the API with an organization token:
 - `GET /api/v1/orgs/<org>/runs/<id>/export.zip` (`kaloko export`): the whole
   run as a zip before it expires; keep it with the issue when the evidence
   must outlive the retention period.
+- Uploads by content hash: `POST …/blobs/missing` with `{"hashes": [sha256…]}`
+  answers what the organization does not store yet, `PUT …/blobs/<sha256>`
+  (header `X-QAwalk-Type: png|webp|html|json`) stores one, and the run's file
+  plan `POST …/runs/<id>/files` takes `{ path, bytes, blob }` entries that
+  point at stored blobs. `kaloko share` does this: unchanged captures are not
+  sent again and a share that broke off resumes when run again.
 - MCP server for agents: see [mcp.md](mcp.md).
 
 Read-only tokens may list but not change anything; keep CI tokens read-only

package/skills/kaloko/reference/design.md

@@ -39,8 +39,10 @@ design/
   the bundle.
 - Links between steps are plain relative links to the page: `<a href="../payment/index.html">`. The canvas
   follows them; `data-kaloko-go="payment"` (or `data-qawalk-go`) moves to that step whatever the `href` says.
-- Reference token values as CSS custom properties (`var(--color-accent)`), so the inspector and the token
-  check see where values come from.
+- Reference token values as CSS custom properties named after the token path (`color.accent` →
+  `var(--color-accent)`), so Dev mode, the step spec and the token check see which token a value comes from.
+  Define interaction states in CSS (`:hover`, `:focus-visible`, `:active`, `:disabled`): Dev mode and the spec
+  read them from the stylesheet.
 - Write pages by the portable HTML rules ([portable-html.md](portable-html.md)): relative URLs only, bundled
   fonts, no CDNs, state in the URL instead of storage, deterministic content, viewport meta and `lang`.
   `kaloko design lint` checks the folder; `kaloko sync` runs it first and stops on errors (things that break on
@@ -94,8 +96,39 @@ Development builds from the design reference:
 - `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
+  [Implement from the approved design](#implement-from-the-approved-design).
 - Translate to the project's stack with the project's own skills; keep the step ids and the token names.
 
+## Implement from the approved design
+
+Use this when you build or change a screen that has an approved design step (a design reference, or a version
+the person names). The step spec says what was approved in the terms you write code in: elements in page order
+with role, accessible name and selector, and their colors, typography, spacing, radius, shadow and layout, each
+value with the DTCG token it comes from. People see the same data in the canvas: *Dev mode* (`D`) in the step
+detail.
+
+1. **Read the spec** of each step you build: `kaloko spec <step>` (default `--ref design`; `--ref v4`, `draft` or a
+   run id), or MCP `get_step_spec`. `--json` gives `qawalk.spec.v1` (`schemas/spec.v1.json`).
+2. **Implement with the tokens.** A line such as `button "Pay" 120×44 bg #2e6bff=color.brand.primary · pad 12px
+   20px=space.3 space.5` means `background: var(--color-brand-primary); padding: var(--space-3) var(--space-5)`
+   (the custom property is the token path with dots as dashes) or the project's own token mechanism. `not a token;
+   nearest x` means the design itself used a raw value: ask the designer before you copy it, and say so in the PR.
+   `:hover`, `:focus`, `:active` and `:disabled` lines are states to build; `(light)` names the mode of a value.
+   Keep the roles and names: they are how the implementation is matched with the design.
+3. **Walk it** with `packs: [design]` on the implementation steps; the capture then stores the implementation's
+   spec next to the screenshot.
+4. **Check drift**: `kaloko drift [step]` compares the walked run with the design reference of the linked design
+   branch and exits 1 while something differs. A shared run: MCP `get_step_drift` (`run`: id or `latest`).
+   Findings name the element, the expected token and value, and what the page has; `typed raw` means the value
+   is right but should come from the token; `not found` means the design's element (by role and name) is missing.
+5. **Fix and repeat** until drift is clean or what is left is a decision for a person (a missing element on
+   purpose, a raw value the designer accepted); report those in the PR instead of hiding them.
+
+Specs exist for captures made with the current CLI: walk the design and sync again if `kaloko spec` says there is
+none. The pixel, structure and token checks of the design pack (`AC801`–`AC803`) still run in `kaloko evaluate`;
+drift is the per-element view an agent can act on.
+
 ## Your data is yours
 
 Everything exports in open formats, readable without Kaloko:

package/skills/kaloko/reference/environments.md

@@ -13,6 +13,11 @@ them; do not work around a block.
 Test data preparation for review and staging belongs to the project's CI
 prepare step; assume it exists and create only what the scenario itself needs.
 
+Pull request previews (Vercel, Netlify, Cloudflare Pages, review apps) are an
+environment whose URL comes from CI: `preview: { base_url: ${KALOKO_PREVIEW_URL} }`,
+which `kaloko ci github|gitlab` adds and `kaloko ci preview-url` fills; see
+[ci.md](ci.md).
+
 ## Who does what
 
 Kaloko needs evidence in its format: captures of screens and e-mails in a run.