kaloko 0.3.0

package/schemas/tokens.v1.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qawalk.com/schemas/tokens.v1.json",
+  "title": "qawalk.tokens.v1",
+  "description": "A project's token set in the W3C Design Tokens Community Group format (#42): nested groups, tokens with $value and optional $type (string values or the 2025.10 objects for colors, dimensions, durations and composite types), aliases as {group.token} or {\"$ref\": \"#/pointer\"}, $extends, $root and $deprecated; or a DTCG resolver (sets, modifiers, resolutionOrder) with its sources inlined. Top-level groups named like a mode (light, dark, high-contrast, or listed in $extensions[\"qawalk.modes\"]) overlay the rest in that mode. Stored versioned per project; tokens.json in the design folder is the same format.",
+  "$defs": {
+    "group": {
+      "type": "object",
+      "properties": {
+        "$type": {
+          "type": "string"
+        },
+        "$description": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "$ref": "#/$defs/token"
+          },
+          {
+            "$ref": "#/$defs/group"
+          }
+        ]
+      }
+    },
+    "token": {
+      "type": "object",
+      "required": [
+        "$value"
+      ],
+      "properties": {
+        "$value": {},
+        "$type": {
+          "type": "string"
+        },
+        "$description": {
+          "type": "string"
+        }
+      }
+    },
+    "set": {
+      "type": "object",
+      "properties": {
+        "$extensions": {
+          "type": "object",
+          "properties": {
+            "qawalk.modes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/group"
+      }
+    },
+    "resolver": {
+      "type": "object",
+      "required": [
+        "resolutionOrder"
+      ],
+      "properties": {
+        "version": {
+          "type": "string"
+        },
+        "sets": {
+          "type": "object"
+        },
+        "modifiers": {
+          "type": "object"
+        },
+        "resolutionOrder": {
+          "type": "array"
+        }
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "$ref": "#/$defs/resolver"
+    },
+    {
+      "allOf": [
+        {
+          "not": {
+            "required": [
+              "resolutionOrder"
+            ]
+          }
+        },
+        {
+          "$ref": "#/$defs/set"
+        }
+      ]
+    }
+  ]
+}

package/skills/kaloko/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: kaloko
+description: >
+  Use when a task or flow needs an acceptance or regression walkthrough with
+  evidence: writing or updating ACCEPTANCE.md or qa/scenario.yml, running a
+  scenario on local, review, staging or production (readonly), capturing
+  screens and e-mails, evaluating criteria, or building and sharing the
+  Kaloko canvas, for web pages as well as Android, iOS and desktop apps,
+  including checking many pages of one template at once (magazine articles,
+  product pages, an SEO page catalogue). Also when someone asks what a
+  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).
+---
+
+# Kaloko
+
+Kaloko turns an acceptance plan into a run bundle (`run.json` + screenshots,
+HTML, evaluations) and renders it as a flow canvas. You fill it with content;
+the canvas, storage and collaboration are the service.
+
+## Done means
+
+- The scenario validates (`kaloko validate`).
+- Every step in the requested scope has a capture, or the summary says why not.
+- The captures are evaluated (`kaloko walk` ends with the verdicts; after
+  `kaloko capture` run `kaloko evaluate`) and `kaloko build` ran; you report the summary line,
+  failing criteria with evidence, and the preview path (or shared URL).
+- When the run was shared, its URL and the summary are in the issue or PR
+  the work belongs to, 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).
+- On a design environment: the folder follows the bundle rules, `kaloko walk`
+  and `kaloko sync` ran, `kaloko status` shows no conflict, and you read the
+  draft's feedback; a version is published only when the person asked.
+
+## You may do without asking
+
+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
+the design folder, walk, and sync the draft (including taking others' steps
+with `--theirs`). Move to the trash runs you uploaded in this session that
+were superseded before anyone looked at them (debug rounds: no comments, no
+verdict), and run `kaloko prune` without `--yes` to see what a clean-up would do.
+
+## Ask first
+
+Changing acceptance criteria or scope, any production run, 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
+(`kaloko prune --yes`), trashing someone else's run, archiving a scenario, and
+anything the environment profile blocks. Never trash an accepted run, a
+baseline, a run with review comments, or a run linked from an open PR or issue
+comment. Ask the person
+for secret values (passwords, tokens, gate credentials) and for sign-ins only
+they can do; never write secrets into the config, a scenario or a script.
+
+## Where to look
+
+- Writing or updating the plan and scenario: [reference/acceptance.md](reference/acceptance.md)
+- Android, iOS (Simulator), Electron and macOS apps, or screens captured by
+  another tool (Maestro, Appium, XCUITest) with their UI tree:
+  [reference/apps.md](reference/apps.md)
+- Many pages of one template in one step (articles, products, an SEO
+  catalogue from a sitemap or a listing), with an index on the canvas:
+  [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, 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:
+  [reference/environments.md](reference/environments.md)
+- Sharing, reviewer feedback, mentions, inbox, verdicts and baselines, and
+  cleaning up runs (trash, prune, keep, archive):
+  [reference/collaboration.md](reference/collaboration.md)
+- Reading runs, feedback and the inbox over MCP instead of the CLI:
+  [reference/mcp.md](reference/mcp.md)
+- Refreshing a manual, course or product documentation from the newest
+  captures (latest URLs, changed steps, webhooks, export):
+  [reference/documentation.md](reference/documentation.md)
+- Designing in a design environment (bundle, sync and publish, comments,
+  references, handoff, tokens, the design pack, canvas edits, branches, HTML
+  view, bringing your own design skill): [reference/design.md](reference/design.md)
+- Command reference: `kaloko help`; when something does not work (Chrome,
+  token, environment URL, evaluator key), run `kaloko doctor` first and fix
+  what it marks ✕.
+
+Project configuration is `kaloko.config.yml` in the repository root.
+Project skills may add conventions (paths, test data, locales); follow them
+where they are more specific.

package/skills/kaloko/reference/acceptance.md

@@ -0,0 +1,208 @@
+# Acceptance plan and scenario
+
+Two files per task, next to the task documentation:
+
+- `ACCEPTANCE.md` — for people. Goal, flow (Mermaid), steps with purpose and
+  criteria `AC<n>`, variants, locales, environments, execution per step,
+  change log. Template: `templates/ACCEPTANCE.md` (Czech: `templates/cs/`).
+- `qa/scenario.yml` — for the runner. Schema `schemas/scenario.v1.json`,
+  example `templates/scenario.yml`.
+
+Long-lived flows that outlive tasks (checkout, SEO on production) live in
+`qa/flows/*.yml` with `kind: flow`.
+
+## Creating or updating
+
+Read the task documentation and recent commits first. The plan states intent;
+the scenario is its executable form. When sources disagree or intent is
+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.
+
+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
+(title, H1, description as purpose; packs seo, a11y, perf, console). Then
+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:
+`seo` checks one H1, title and description length, canonical, hreflang for
+every locale, Open Graph, indexing, viewport, `html lang`, overflow and
+console; `usability` asks the evaluator about purpose, one primary action
+and link texts and checks unlabeled inputs. 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.
+
+- `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.
+- `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).
+  Override a limit with an own criterion of the same id, 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
+  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:
+  - 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;
+  - a plain-language message with a way forward (semantic);
+  - no console errors. The document's own error status is not counted.
+
+## Error pages
+
+Every site has them and they are easy to forget. Give each one its own
+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
+  `{ 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
+  canvas shows 3xx–5xx on the node, so a normal step that suddenly answers
+  500 stands out. On a stack, `http_status` with `min: 200, max: 299` finds
+  broken pages among hundreds.
+- **5xx and maintenance pages:** you cannot trigger them on production.
+  Use a test route the project provides (for example `/500` on a review
+  app), the static error page the server serves (`/500.html` answers 200,
+  so override AC601 with `value: 200`), or a local environment where the
+  person agrees to stop a dependency. Say which one you used.
+- **Access errors:** 401/403 for a signed-out visitor on a protected
+  address, and an expired link (410). Walk these with the right session.
+
+## Many pages of one template
+
+When the plan says "every article / product / landing page must …", do not
+write one step per page. Use one `kind: stack` step whose `items` come from
+a sitemap, a listing, a file or a script, with the criteria every page must
+meet. The canvas shows it as a stack with an index. The plan keeps one
+`### <step-id>` section for it, naming the source and the limit. See
+[stacks.md](stacks.md).
+
+## Capture quality
+
+The default capture is WebP at 1× — right for daily acceptance, small and fast on the canvas. For
+documentation, manuals and training material set print quality on the scenario or on single steps:
+
+```yaml
+capture:
+  format: png          # lossless
+  scale: 2             # 2× device pixels, crisp in a PDF
+  mask: ["[data-qa=email]", ".customer-name"]   # solid box over personal data (image only; the HTML keeps it)
+  annotate: true       # numbered marks on the elements of criteria with `highlight`, in criteria order
+```
+
+A node's `capture:` overrides the scenario's. Crops for a manual take padding in step scripts:
+`await crop('#checkout-summary', 'Order summary', { padding: 16 })`. Print quality costs storage (a
+2× PNG is several times a 1× WebP), so keep it for documentation scenarios, not for every run. The
+canvas still loads a small WebP thumbnail; the lightbox and `latest.image` serve the full file.
+Masks hide pixels, not the captured HTML: do not use production personal data in documentation runs.
+
+## Keeping plan and scenario aligned
+
+`kaloko validate <scenario.yml> --coverage` compares `AC<n>` lines under each
+`### <step-id>` heading of the plan (`source`) with the scenario: planned
+criteria without a check fail the command, checks without a planned criterion
+are listed. The canvas shows the same card ("Plan coverage") and marks
+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.
+
+## Naming and linkage
+
+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.
+
+## Session and consent
+
+Default, unless the plan says otherwise: a run starts as a new visitor
+(`walk` clears cookies and storage before the first step; agents call
+`kaloko session reset`). When the site shows a consent dialog:
+
+1. the first screen is captured with the dialog still open — it is part of
+   what a new visitor sees, with one criterion that it appears;
+2. the next step accepts it (`steps/consent.mjs`, installed by `kaloko init`,
+   handles common consent libraries and captures the same screen without the
+   dialog; criterion: the dialog is gone);
+3. every later screen runs without the dialog. Do not repeat consent
+   criteria on them — a returning dialog is visible on the canvas anyway.
+
+Skip the consent step when the site has no consent dialog. Change the order
+in `ACCEPTANCE.md` when the plan tests consent itself (rejecting, settings,
+per-category choices) or needs another session state (signed-in user,
+returning visitor). The plan is the source of truth; this is only the default.
+
+## Writing criteria
+
+Each criterion gets exactly one check:
+
+- `deterministic` for anything countable or exact: presence, counts, text,
+  prices, attributes, overflow, console errors, title/meta/canonical.
+- `semantic` for judgement: clarity, separation of consents, whether copy
+  fits the purpose. Write the question in English, yes = met, one condition
+  per question. Add `true`/`false` for edge cases and `scope` (CSS selector)
+  to send only the relevant region.
+- `manual` when neither works; a reviewer decides on the canvas.
+
+A semantic question with two conditions ("says that the draft is live **and**
+shared, so everyone sees changes", "says how to publish **and** what
+publishing saves") lands in the middle of the score range and stays
+`needs_review` even when the page is clear, because the evaluator weighs the
+part it is less sure about. Split it into one criterion per condition, scope
+it to the element that should say it (`scope: ".draft-panel"`, not `body`),
+and put the expected wording into `true`:
+
+```yaml
+- { id: AC6, text: Says the draft is live, check: { type: semantic, question: "Does the draft panel say that changes appear live for everyone who has the draft open?", scope: ".draft-panel", true: "Yes: it states that others see changes as they happen." } }
+- { id: AC7, text: Says how to publish, check: { type: semantic, question: "Does the draft panel say how to publish a new version?", scope: ".draft-panel" } }
+- { id: AC8, text: Says what publishing saves, check: { type: semantic, question: "Does the draft panel say what publishing a version saves?", scope: ".draft-panel" } }
+```
+
+When the exact wording is fixed and matters, a `text_matches` check is better
+than a question.
+
+Numbers, dates and counts never go to `semantic`. Add `highlight` when the
+check selector is not the element a reviewer should see.
+
+Text checks (`text_matches`, `text_absent`, `title_matches`) run a JavaScript
+regex on the element's `innerText`, which follows CSS `text-transform`: a
+button styled uppercase reads `VYTVOŘIT`. Add `flags: i` to ignore case
+(also `m`, `s`) instead of writing `[Vv][Yy]…`. Keep patterns specific: a
+white-label check for `vyvolej` also matches the Czech verb "Vyvolej si";
+anchor it (`vyvolej\.to`).
+
+Describe every relevant variant as nodes and `alt` edges, even when a given
+run covers only part of it. Decisions are `kind: decision` nodes.
+
+## People in the flow
+
+When a flow involves more than one person (a guest who buys, a member who
+shares a link, the friend who arrives through it, an operator in the console),
+list them in `ACCEPTANCE.md` under "People in the flow": one line per person
+with who they are, what test data they need, and what they must not see.
+In `scenario.yml` declare them as `sessions` and give every non-decision node
+a `session`. `kaloko walk` keeps one browser context per session and locale,
+so nobody signs anybody out; step scripts receive `session` (`key`, `title`,
+`mailbox`, `account`) and `session.credentials` from
+`environments.<env>.accounts.<account>` (see environments.md).
+E-mail nodes default to the session's `mailbox`. `blocked_on: [production]`
+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.

package/skills/kaloko/reference/apps.md

@@ -0,0 +1,161 @@
+# Mobile and desktop apps
+
+Kaloko walks native apps the way it walks web pages. Each step becomes a
+screenshot, a UI tree, checked criteria and a place on the canvas. Only the
+driver differs, and it is chosen by the scenario's `platform`.
+
+| platform | Driven by | UI tree | Interactions |
+|---|---|---|---|
+| `android` | `adb` (emulator or USB device) | uiautomator, in dp | deep links, tap by selector or point, type, back |
+| `ios` | `xcrun simctl` (iOS Simulator) | `idb` when installed, otherwise text by OCR (macOS Vision) | deep links; taps and typing need `idb` |
+| `electron` | Playwright Electron | the full DOM: every web check applies | everything Playwright does (`page`) |
+| `desktop` | macOS window of a named app | macOS accessibility tree, otherwise OCR | none built in: use your tool, AppleScript or a person |
+
+Anything else, including a real iPhone, Windows apps, Flutter/React Native
+under Detox, Maestro flows or XCUITest, is captured by import:
+
+```bash
+npx kaloko capture --step checkout --image shot.png --tree hierarchy.xml --device "Pixel 8" --density 2.625
+```
+
+`--tree` accepts:
+
+- uiautomator or Appium Android XML;
+- Appium iOS XML (`XCUIElementType…`);
+- `idb ui describe-all --json`;
+- Maestro `hierarchy` JSON;
+- Kaloko's own `qawalk.tree.v1`.
+
+`--ocr` reads the text from the image instead (macOS). `--density` or
+`--scale` converts device pixels to dp or points. Without either, Kaloko
+infers the scale from the tree.
+
+## Setting it up
+
+The config names the app per environment; the scenario only says the
+platform:
+
+```yaml
+# kaloko.config.yml
+environments:
+  staging:
+    app:
+      android: { package: com.acme.shop.staging, apk: build/app-staging.apk, reset: true }
+      ios: { bundle: com.acme.shop, app: build/Shop.app, device: iPhone 17 }
+  desktop:
+    app:
+      electron: { main: dist/main.js }          # or executable: path to the packaged app
+      # desktop: { name: Notes }                # a macOS app by its window owner name
+```
+
+```yaml
+# qa/flows/shop-android.yml
+schema: qawalk.scenario.v1
+id: SHOP-android
+platform: android
+locales: [cs, en]
+viewports: { phone: [412, 915] }               # a label and the nominal size; the device decides the real one
+nodes:
+  - id: product
+    kind: screen
+    title: Product detail
+    path: shop://product/42                    # deep link; https://… universal links work too
+    packs: [app]
+    execution: { strategy: script, instructions: Open the product by deep link. }
+    criteria:
+      - { id: AC1, text: Price in CZK, check: { type: deterministic, assert: text_matches, selector: '[id$=price]', pattern: '^[\d ]+ Kč$' } }
+      - { id: AC2, text: Add to cart, check: { type: deterministic, assert: exists, selector: 'button[text="Do košíku"]' } }
+  - id: cart
+    kind: screen
+    title: Cart
+    execution: { strategy: script, script: steps/add-to-cart.mjs, instructions: Tap Add to cart, then the cart icon. }
+    criteria: [...]
+```
+
+**Stepping through the app**
+
+- Screens of an app scenario do not need a `path`. A step script reaches
+  them, or a person or agent does and then runs `kaloko capture`.
+- Every locale starts the app fresh. `reset: true` clears the app data, so
+  each locale starts as a new user.
+- The app language is set per locale: Android 13+ app locales, iOS
+  `-AppleLanguages`, Electron `--lang`.
+
+**Step scripts**
+
+A script gets `{ app, page, locale, env, run, capture, link }`:
+
+```js
+// steps/add-to-cart.mjs
+export default async ({ app, link, capture }) => {
+  await app.link(link('product'))                  // the product step's deep link
+  await app.tap('button[text="Do košíku"]')
+  await app.wait({ text: 'V košíku' })
+  await app.tap('[id$=cart]')
+  await capture()
+}
+```
+
+- `app.tap`, `app.wait` and `app.type` take app selectors. `app.tap({ x, y })`
+  taps by coordinates, in dp or points.
+- On Electron, selectors are CSS and `page` is the Playwright page, so
+  any Playwright code works there.
+
+## Selectors and checks on the UI tree
+
+Selectors are CSS-like, over roles and attributes:
+
+- `button[text="Sign in"]`
+- `[id$=login]` (Android resource-id or iOS accessibility id)
+- `text[text~="^\d+ Kč$"]` (regex)
+- `[name*=close i]` (case-insensitive)
+
+Operators are `=`, `^=`, `$=`, `*=` and `~=`, and commas separate
+alternatives. The roles are button, text, textbox, image, checkbox, switch,
+radio, slider, combobox, list, cell, tab, tablist, toolbar, link, alert,
+dialog, webview and group.
+
+- **Checks that work on apps:** `exists`, `absent`, `count`,
+  `text_matches`, `text_absent`, `attr_equals`, `a11y_names`, and
+  `no_console_errors` (errors from the Android app log).
+- **App-only checks:**
+  - `app_labels`: every control has a label;
+  - `app_touch_targets`: 48 dp on Android, 44 pt on iOS, or `min`;
+  - `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
+  the screen's purpose and next action.
+- **Web-only checks** (`no_overflow`, `http_status`, meta, `a11y_contrast`,
+  `perf_*`): these are "not evaluated" on app captures. Do not put them on
+  app steps.
+- **OCR trees:** these have text only, so role checks (labels, touch
+  targets) are not evaluated there. Say so in the report and install `idb`
+  when those checks matter.
+
+Semantic criteria read the tree as an outline (roles and texts), so write
+questions about what is on the screen, not about the markup.
+
+## Reading the canvas
+
+- Phone captures sit in a device frame, and desktop captures in a window
+  frame.
+- The lightbox has a **UI tree** panel: search it, and click an element to
+  outline it on the screenshot. Criteria highlights use the same boxes.
+- The run card shows the platform and the device.
+- `kaloko evaluate --recheck` re-runs the checks on the stored tree, so no
+  device is needed after a criteria fix.
+
+## Rules
+
+- **Devices:** never install on a person's own phone or sign in with
+  real accounts without asking. Emulators and simulators are yours to
+  start, reset and install builds on.
+- **Production apps:** production apps (store builds) are read-only in
+  spirit. Walk them only with deep links and screens that change no data,
+  unless the person agrees.
+- **Sign-in:** ask the person for credentials, or ask them to sign in once
+  on the emulator. Never write credentials into a script.
+- **macOS permissions:** desktop capture needs Screen Recording, and the
+  accessibility tree needs Accessibility. If macOS refuses, tell the person
+  which permission to grant to which app. Do not work around it.