kaloko 0.15.0 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Your AI agents build; Kaloko walks every screen, puts it on one canvas and records who approved what.",
   "keywords": [
     "qa",
@@ -32,7 +32,8 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node scripts/test.mjs"
+    "test": "node scripts/test.mjs",
+    "version": "node scripts/cli-catalogue.mjs && git add worker/src/cli-latest.json"
   },
   "dependencies": {
     "ajv": "^8.20.0",

package/schemas/config.v1.json

@@ -8,7 +8,9 @@
   "properties": {
     "schema": { "const": "qawalk.config.v1" },
     "org": { "type": "string", "description": "Organization slug on kaloko.app." },
-    "project": { "type": "string" },
+    "project": { "type": "string", "description": "Slug of the Kaloko project runs of this repository belong to (a scenario's project: wins)." },
+    "project_name": { "type": "string", "maxLength": 80, "description": "The name people see for that project on Kaloko (ECO Podcasty). A share creates a missing project with it; kaloko projects sync renames an existing one." },
+    "product": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,79}$", "description": "Slug of a product on Kaloko the project is part of; kaloko projects sync adds the project to it." },
     "products": {
       "type": "object",
       "description": "Optional: what is released and versioned as a whole and has its own visual changelog (docs/DOCS-CHANGELOG.md). Without it the project is the product. Keys are product slugs.",

package/schemas/run.v1.json

@@ -281,6 +281,10 @@
         "slug": {
           "type": "string"
         },
+        "name": {
+          "type": "string",
+          "description": "The project's name from project_name: in kaloko.config.yml; a project that a share creates gets it."
+        },
         "repo": {
           "type": [
             "string",

package/schemas/scenario.v1.json

@@ -373,6 +373,24 @@
           "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" }
         },
+        "details": {
+          "type": "array",
+          "maxItems": 20,
+          "description": "Named details for user guides and docs: one element in the part of the page around it (its section or card), outlined, captured in every locale and viewport. Docs show one with ![…](kaloko:<scenario>/<step>#<id>).",
+          "items": {
+            "type": "object",
+            "required": ["id", "name", "selector"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,59}$", "description": "Stable id, used in docs references (#add-to-cart) and file names." },
+              "name": { "$ref": "#/$defs/localized", "description": "What the reader looks at, e.g. \"Add to cart button\"; one text or one per locale." },
+              "selector": { "type": "string", "minLength": 1, "description": "CSS selector of the element; the first match is outlined." },
+              "context": { "type": "string", "minLength": 1, "description": "How much of the page around it: section (the nearest section or landmark), card (the nearest card, list item or framed box), page (one screen around it) or a CSS selector of an ancestor. Default: the nearest section or card at least 480 × 240 px, at most one screen." },
+              "padding": { "type": "integer", "minimum": 0, "maximum": 200, "description": "Pixels of page around the context (default 16)." },
+              "states": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$" }, "description": "Step states to take it in (default: every state the step is captured in)." }
+            }
+          }
+        },
         "items": {
           "type": "object",
           "additionalProperties": false,

package/skills/kaloko/SKILL.md

@@ -26,9 +26,9 @@ description: >
   Clef triage findings (experimental) to read, mention or answer, when
   a run's health (the advisory checks of packs: SEO, accessibility,
   performance, console) should be checked, fixed or adopted into acceptance,
-  and when a team's own repository turns runs into regulated documentation
-  (requirement refs, kaloko evidence, the evidence package, the evidence.ready
-  webhook).
+  and when a team's own repository turns runs into quality evidence for its
+  QMS or GxP (requirement refs, kaloko evidence, the evidence package, the
+  evidence.ready webhook).
 ---
 
 # Kaloko
@@ -89,7 +89,9 @@ verdict), and run `kaloko prune` without `--yes` to see what a clean-up would do
 Draft and edit the Unreleased section of the changelog (`kaloko changelog draft
 --apply`) and add step references to it and to guides. Put the products of the
 config on Kaloko (`kaloko products sync`: it records no release) and list them
-(`kaloko products list`). Write, translate and fix
+(`kaloko products list`). Create the project the config names
+(`kaloko projects sync` or `kaloko projects create` with the name the person
+gave). Write, translate and fix
 guides in the docs folder, run `kaloko docs check`, and export them for a docs
 site (`kaloko export docs --format …`) into a local folder.
 
@@ -105,6 +107,9 @@ design reference or baseline, merging a design branch, keeping your version of
 a step in a sync conflict (`--mine`), turning on `html_view`, turning on recordings for
 a whole project (`capture.record` in the config: storage), a real clean-up
 (`kaloko prune --yes`), trashing someone else's run, archiving a scenario,
+renaming a project or restricting it (`kaloko projects rename`, a `kaloko
+projects sync` that would rename), picking one site of a repository that
+holds several (ask which one before `kaloko init` or a walk),
 recording a release (`kaloko release`) or asking to publish a changelog,
 publishing docs (`kaloko docs publish`, `--reviewed` above all: it says a
 person checked the text), writing a release workflow (`kaloko ci github
@@ -125,7 +130,11 @@ only when a person says that value may be uploaded.
 
 - A new project or an organization without runs of its own (install, sign in,
   the sample run, the first flow from a URL or a task, share, point the person
-  to the canvas): [reference/first-run.md](reference/first-run.md)
+  to the canvas), and naming the project on Kaloko (`project_name:`,
+  `kaloko projects create|rename|sync`): [reference/first-run.md](reference/first-run.md)
+- A repository with several sites or apps (monorepo, Rails engines, Folio
+  sites): ask which one, then `kaloko init --site … --base-url …`:
+  [reference/first-run.md#several-sites-in-one-repository](reference/first-run.md#several-sites-in-one-repository)
 - Writing or updating the plan and scenario: [reference/acceptance.md](reference/acceptance.md)
 - Android, iOS (Simulator or a real iPhone), Electron, macOS and Windows apps,
   several devices of one app, WebViews inside apps, or screens captured by
@@ -169,8 +178,9 @@ only when a person says that value may be uploaded.
   [reference/collaboration.md](reference/collaboration.md)
 - Reading runs, feedback and the inbox over MCP instead of the CLI:
   [reference/mcp.md](reference/mcp.md)
-- Evidence for regulated work (GxP): requirement `refs:`, `kaloko evidence`,
-  the evidence package and its check, the `evidence.ready` webhook, feeding a
+- Quality evidence for a team's QMS (ISO 9001, ISO 13485, IEC 62304, ISO 27001;
+  GxP is the strictest case): requirement `refs:`, `kaloko evidence`, the
+  evidence package and its check, the `evidence.ready` webhook, feeding a
   team's own document templates, signatures and what an agent must never do:
   [reference/evidence.md](reference/evidence.md)
 - Filing a returned step or a failing criterion in Jira or Linear, issue keys in
@@ -200,9 +210,12 @@ only when a person says that value may be uploaded.
   tools (relative URLs, no CDNs, state in the URL, deterministic content,
   links between steps; what `kaloko design lint` checks):
   [reference/portable-html.md](reference/portable-html.md)
-- Command reference: `kaloko help`; when something does not work (Chrome,
+- Command reference: `kaloko help` (`kaloko help --json` lists every command,
+  sub-command and option as data); when something does not work (Chrome,
   token, environment URL, evaluator key), run `kaloko doctor` first and fix
-  what it marks ✕.
+  what it marks ✕. When a command answers "… is in kaloko X (you have Y)",
+  the project's kaloko is too old for it: tell the person and suggest the
+  update command from that line; change the dependency only when they agree.
 
 Project configuration is `kaloko.config.yml` in the repository root.
 Project skills may add conventions (paths, test data, locales); follow them

package/skills/kaloko/reference/acceptance.md

@@ -97,8 +97,10 @@ English words; one plain word such as a brand name is left alone).
   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
+  five focus stops are kept as screenshots (step attachments of kind
+  `focus`, "Keyboard focus · HC309" on the canvas, linked to the check; the
+  Health tab shows them under `HC309` and in the tab order) 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.

package/skills/kaloko/reference/docs.md

@@ -14,6 +14,7 @@ A picture in Markdown names a step instead of a PNG file:
 ![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
+![Pay](kaloko:checkout/payment#pay-button)                a named detail of the step (details: in the scenario)
 ![Payment](kaloko:payment)                                a step of the product's default_scenario
 ```
 
@@ -28,6 +29,29 @@ a dialog, a language switch), not for every step. Check a reference with MCP `re
 `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).
 
+## Details for guides
+
+When a guide talks about one control, show that control in its part of the page instead of the whole screen. Declare
+it on the step in the scenario and refer to it with `#<id>`:
+
+```yaml
+details:
+  - id: pay-button                                   # letters, digits, - and _; used in references and file names
+    name: { en: Pay button, cs: Tlačítko Zaplatit }  # one text or one per locale
+    selector: "#pay"                                 # the first match is outlined
+    context: card                                    # optional: section | card | page | a CSS selector of an ancestor
+    padding: 24                                      # optional, px around the context (default 16)
+    states: [error]                                  # optional: only in these states of the step
+```
+
+Without `context` the picture is the nearest section, landmark or card around the element that is at least
+480 × 240 px (90 % of the width on a phone), at most one screen around the element, with a ring drawn around the
+element. Every walk takes each detail in every locale and viewport, masked like the screenshot, as an attachment of
+kind `detail` (canvas: Page tab → Step attachments → Details for guides, with the reference). Only screen steps take
+details. A reference to a detail no accepted run has yet shows the whole screen; `kaloko docs check` warns under
+`missing_details` (the scenario does not declare it) and `no_detail` (no accepted run has it: walk and accept).
+Prefer a detail over a crop when the text names one button, field or message; keep the whole screen for orientation.
+
 Never invent a step id or a version. Use ids from the scenario files and versions from `CHANGELOG.md` or git tags.
 
 ## After a user-visible change

package/skills/kaloko/reference/evidence.md

@@ -1,12 +1,14 @@
-# Evidence for your own documentation (regulated work)
+# Quality evidence for your own documentation
 
 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
+matrices, release summaries for its quality management system (ISO 9001, ISO 13485, IEC 62304, ISO 27001, or GxP
+under 21 CFR Part 11 and EU GMP Annex 11, the strictest case). 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.
+*Quality evidence for your QMS* (it maps the frameworks and has a GxP section). Evidence is a Business feature.
+Kaloko provides evidence; it never makes a team compliant or certified, so never write that it does.
 
 ## The contract
 

package/skills/kaloko/reference/first-run.md

@@ -24,11 +24,17 @@ with a person who knows where to approve it.
 ## From zero to a first shared run
 
 1. `npm install --save-dev kaloko`, then
-   `npx kaloko init --agent claude --org <org>` (it prints the sample link
-   and these steps). Fill `environments` in `kaloko.config.yml` with the URL
-   the app runs on.
+   `npx kaloko init --agent claude --org <org> --project <slug> --project-name "<name>"`
+   (it prints the sample link and these steps). Ask the person how the project
+   should be called on Kaloko when you do not know; the slug is lowercase
+   (`eco-podcasty`), the name is what people see (`ECO Podcasty`). Fill
+   `environments` in `kaloko.config.yml` with the URL the app runs on. When
+   the repository holds several sites, see [Several sites in one
+   repository](#several-sites-in-one-repository) first.
 2. `npx kaloko login`: the person approves a token in the browser. Ask them
-   to; never create or paste tokens yourself.
+   to; never create or paste tokens yourself. Then `npx kaloko projects sync`
+   puts the project of the config on Kaloko with its name (a first
+   `kaloko share` would create it too).
 3. `npx kaloko doctor` and fix what it marks ✕.
 4. Draft the first scenario:
    - public pages: `npx kaloko draft <url> [url…]` writes a read-only
@@ -49,3 +55,30 @@ with a person who knows where to approve it.
 Done means: the scenario validates, the run is shared, its URL and summary
 line are in your reply (and in the issue or PR the work belongs to), and the
 person knows whether the sample or this run is what they should open.
+
+## Several sites in one repository
+
+A monorepo (`apps/*` with their own dev server), a Rails app with engines or
+several Folio sites, or routes split by host: `kaloko init` lists the sites
+it found and drafts no steps, because routes of the whole repository mix the
+sites (favicons, ad endpoints and API routes of another site end up as
+"pages").
+
+1. Ask the person which site the work is about before `init` or a walk. Do
+   not pick one yourself.
+2. Run init for that site, best against the running site so the pages come
+   from its sitemap or its navigation:
+   - `npx kaloko init --site eco-podcasty --base-url http://eco-podcasty.localhost:3000`
+   - `npx kaloko init --site apps/web` (a workspace app: its own routes and dev
+     server; `--base-url` still reads the running site when it is up)
+   Only the host of `--base-url` is asked, with short time limits; offline the
+   code is read.
+3. Read the comment at the top of `qa/flows/main-pages.yml`: it says where the
+   pages came from and which paths were skipped and why. Sharpen the steps;
+   add pages the person names.
+4. When the site is not running and has no routes of its own (a Folio site),
+   `npx kaloko init --site <name> --skeleton` writes a scenario with a TODO;
+   fill it with the pages the person names.
+
+One config can serve one site. For a second site of the same repository use
+another config (`--config kaloko.<site>.config.yml`) with its own `project:`.

package/skills/kaloko/reference/mcp.md

@@ -32,6 +32,7 @@ is null. Projects and products come complete, without pages.
 | `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`, `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 |
+| `upsert_project` | creates a project (`slug`, `name`, `visibility`, `product`; `create: true` refuses an existing one) or renames it; the same rules as `kaloko projects create\|rename\|sync` (a full token; renaming is for the project's admin). Ask before renaming |
 | `get_criteria_verdicts` | reviewer verdicts on manual or overridden criteria of a run |
 | `get_stack_items` | the pages of a stack step (`run_id`, `step`; filters `status`, `criterion`, text): path, URL, title, status and failing criteria with evidence, screenshot URLs |
 | `get_step_recording` | a step's recording and trace (`run_id`, `step`, `locale`, `viewport`, `trace: true` for the full trace): video URLs, duration, its chapter of a flow recording, failed attempts, the trace summary (failed requests, console errors, slowest request); see [recording.md](recording.md). `get_run_summary` lists trace summaries per step too |
@@ -42,7 +43,7 @@ is null. Projects and products come complete, without pages.
 | `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; `video` (mp4, webm, duration_ms) when the step's recording plays (`media=video` / `media=image` in the ref) |
+| `resolve_step_image` | one step reference (`ref` = `kaloko:<scenario>/<step>?…[#<detail>]`, `product`, `version`, `locale`, `viewport`, `detail`) 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); with a detail id the detail's picture and `detail` { id, name, box, size }, or the whole screen with `detail_missing` |
 | `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) |