kaloko 0.5.1 → 0.6.0

package/README.md

@@ -210,6 +210,87 @@ 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.
 
+## A changelog with pictures
+
+Your accepted runs already hold every screen of the release. `CHANGELOG.md`
+can show them: a picture names a step instead of a file, and Kaloko shows the
+accepted capture of it.
+
+```markdown
+- You can pay with Apple Pay in the checkout.
+  ![before](kaloko:checkout/payment?version=prev) ![after](kaloko:checkout/payment)
+```
+
+```bash
+npx kaloko changelog draft            # the Unreleased entry: merged PRs and changed screens, before and after
+npx kaloko changelog draft --apply    # the same, written into CHANGELOG.md (Keep a Changelog)
+npx kaloko release 2.4.0              # record the release and its pictures; prints the changelog page
+```
+
+The draft groups pull requests and commits (Conventional Commits when you
+use them) into Added, Changed, Fixed and Removed; your agent rewrites the
+lines for people. The version comes from what the repository already uses
+(git tags, `package.json`, release-please, changesets, semantic-release);
+when a release tool owns `CHANGELOG.md`, Kaloko only reads it. The page on
+kaloko.app has a slider between before and after, switches language and
+screen size, and links each picture to its flow on the canvas. Share it with
+guests, readers from your company's domain, or publish it with a feed.
+Repositories with several apps list them under `products:` in
+`kaloko.config.yml`.
+
+When release-please, changesets or semantic-release makes your releases,
+`npx kaloko ci github --release` adds a workflow that records each published
+release on Kaloko; your release tool keeps writing `CHANGELOG.md`.
+
+## Docs that keep up with the app
+
+Guides in your `docs/` folder (tutorials, how-to guides, reference,
+explanation) use the same step references, so their pictures never go stale.
+A Czech translation of `pay.md` is `pay.cs.md` next to it.
+
+```bash
+npx kaloko init --docs=full           # docs folders with a template in each
+npx kaloko docs check                 # broken references, stale sections, missing translations; exit 1 in CI
+npx kaloko docs publish               # the docs on kaloko.app: versions, languages, screens, search
+npx kaloko export --format docusaurus # or md, vitepress, mkdocs, html, pdf, json: pictures as files
+```
+
+When a screen changes after its guide was written, the section on kaloko.app
+says "the screen changed in 2.4 — check the text", and `kaloko docs check`
+lists it. A guide plays as a walkthrough, one step at a time, and readers can
+ask for a "What's new" e-mail with every release.
+
+## Jira, Linear, Slack and Teams
+
+When a reviewer returns a step, the fix usually gets planned in Jira or
+Linear. Create the issue from the step, on the canvas or from the terminal:
+
+```bash
+npx kaloko issue create --step checkout --to jira --criterion AC2
+```
+
+The issue gets the screenshot, the criterion, the reviewers' notes and a link
+back to the step. When it is done in the tracker, the comment on the step is
+resolved. A branch or pull request title that names the issue (`WEB-12`, or
+Linear's `eng-42`) links the run to it. Slack and Teams channels are chosen per
+project in Settings → Integrations, with the events each channel wants and
+quiet hours.
+
+## Pages checked on a schedule
+
+A read-only scenario of public or gated pages can run on Kaloko's own
+browsers every morning, with nobody starting the CLI (Business plan):
+
+```bash
+npx kaloko schedule add --scenario qa/flows/public.yml --env production --every day --at 5
+npx kaloko schedule export github --scenario qa/flows/checkout.yml --env staging   # the full walk in GitHub Actions
+```
+
+Hosted runs open pages (HTTP Basic and saved sessions work), take full-page
+screenshots in every locale and viewport and check selectors and text. Steps
+that click or type, apps and local environments need the full walk, which the
+exported workflow runs on the same schedule.
+
 ## Design (Kaloko Design)
 
 Design the screens of a flow as live HTML with your own agent and skills, in the same scenario that development
@@ -238,6 +319,28 @@ npx kaloko spec payment                   # elements, styles → tokens, states
 npx kaloko walk && npx kaloko drift       # expected token vs actual value per element; exit 1 while it differs
 ```
 
+Each published version says what changed since the previous one, step by step: the text that moved, the
+viewports that look different, the tokens that changed. Read it before publishing and write your own where the
+reason matters:
+
+```bash
+npx kaloko share --notes-preview          # what the version notes would say
+npx kaloko share --notes notes.md         # a summary, then "step-id: what changed" lines
+```
+
+Design in Figma? Import the frames as design steps and make them the design reference without redrawing them.
+Frames match steps by name (`Payment / mobile`); each step gets the frame image, its text layers with their type
+and colors, and the file's variables as `tokens.json`. It goes one way: prototype links and components stay in
+Figma. Without an API token, import a folder of frames exported from Figma.
+
+```bash
+FIGMA_TOKEN=figd_… npx kaloko design import figma "https://www.figma.com/design/<key>/Shop" --scenario qa/flows/checkout.yml
+npx kaloko design import figma ./figma-export --scenario qa/flows/checkout.yml
+```
+
+Looking for where a pattern is already used? `npx kaloko screens "empty cart"` searches the newest screenshot of
+every step across your flows (also at `/<org>/screens` on kaloko.app and MCP `search_screens`).
+
 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`.

package/package.json

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

package/schemas/changelog.v1.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qawalk.com/schemas/changelog.v1.json",
+  "title": "qawalk.changelog.v1",
+  "description": "The visual changelog as data (docs/DOCS-CHANGELOG.md → Exports): releases newest first with their Keep a Changelog groups and items, each item with the pictures its step references resolve to. Written by src/lib/docs-export.mjs changelogJson; served by GET …/docs/export?format=json and the Download menu of the changelog and docs pages; kaloko export --format json saves it. image is a link for the reader who exported it (signed links expire); canvas opens the step on Kaloko when the reader may see the run.",
+  "type": "object",
+  "required": ["schema", "product", "releases"],
+  "properties": {
+    "schema": { "const": "qawalk.changelog.v1" },
+    "product": {
+      "type": "object",
+      "required": ["slug"],
+      "properties": {
+        "slug": { "type": "string" },
+        "name": { "description": "A name, or names per language ({ \"en\": …, \"cs\": … }).", "oneOf": [{ "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" }] }
+      }
+    },
+    "generated_at": { "type": ["string", "null"], "format": "date-time" },
+    "releases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["version", "groups"],
+        "properties": {
+          "version": { "type": "string" },
+          "released_on": { "type": ["string", "null"], "description": "YYYY-MM-DD" },
+          "tag": { "type": ["string", "null"] },
+          "notes": { "type": "string", "description": "Text before the first group." },
+          "groups": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["name", "items"],
+              "properties": {
+                "name": { "type": "string", "description": "Added, Changed, Deprecated, Removed, Fixed, Security, or the heading as written." },
+                "heading": { "type": "string" },
+                "items": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": ["text", "pictures"],
+                    "properties": {
+                      "text": { "type": "string", "description": "The item's words without pictures and comments." },
+                      "pictures": {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "required": ["ref", "ok"],
+                          "properties": {
+                            "ref": { "type": "string", "description": "The step reference kaloko:<scenario>/<step>[?…]." },
+                            "ok": { "type": "boolean", "description": "false: no accepted picture for this reference." },
+                            "scenario": { "type": "string" },
+                            "step": { "type": "string" },
+                            "title": { "type": ["string", "null"] },
+                            "locale": { "type": "string" },
+                            "viewport": { "type": "string" },
+                            "run": { "type": ["string", "null"] },
+                            "version": { "type": ["string", "null"], "description": "The release the picture belongs to (null: the newest accepted)." },
+                            "image": { "type": ["string", "null"] },
+                            "canvas": { "type": ["string", "null"] }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "docs": {
+      "type": "array",
+      "description": "The docs pages in the export (one language).",
+      "items": {
+        "type": "object",
+        "required": ["path", "title"],
+        "properties": { "path": { "type": "string" }, "lang": { "type": ["string", "null"] }, "title": { "type": "string" }, "kind": { "type": ["string", "null"], "enum": ["tutorials", "how-to", "reference", "explanation", null] } }
+      }
+    }
+  }
+}

package/schemas/config.v1.json

@@ -9,6 +9,13 @@
     "schema": { "const": "qawalk.config.v1" },
     "org": { "type": "string", "description": "Organization slug on kaloko.app." },
     "project": { "type": "string" },
+    "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.",
+      "propertyNames": { "pattern": "^[a-z0-9][a-z0-9._-]{0,79}$" },
+      "additionalProperties": { "$ref": "#/$defs/product" }
+    },
+    "docs": { "$ref": "#/$defs/docs" },
     "scenarios": { "type": "array", "items": { "type": "string" }, "description": "Glob patterns of scenario files." },
     "output": { "type": "string", "description": "Run folder; default tmp/kaloko (tmp/qawalk when only that one exists)" },
     "browser": {
@@ -106,6 +113,45 @@
     }
   },
   "$defs": {
+    "product": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "name": { "oneOf": [{ "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" }, "description": "Name per language, e.g. { en: Web shop, cs: E-shop }." }] },
+        "version": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Where the product's version comes from. Default: detected (release-please, changesets, semantic-release, package.json, pyproject.toml, Cargo.toml, else git tags v*).",
+          "properties": {
+            "source": { "enum": ["auto", "git-tag", "package.json", "release-please", "changesets", "semantic-release", "pyproject", "cargo", "gemspec", "manual"] },
+            "path": { "type": "string", "description": "File that holds the version (package.json of the app, the release-please manifest)." },
+            "pattern": { "type": "string", "description": "Git tag pattern with one *, e.g. shop-v* (default v*)." }
+          }
+        },
+        "docs": { "$ref": "#/$defs/docs" },
+        "project": { "type": "string", "description": "The Kaloko project people review this product in." },
+        "projects": { "type": "array", "items": { "type": "string" }, "description": "Several projects that work on this product." },
+        "modules": { "type": "array", "items": { "type": "string" } },
+        "reference_env": { "type": "string", "description": "Environment whose accepted runs the pictures come from (default: any)." },
+        "default_scenario": { "type": "string", "description": "Scenario of short step references (kaloko:<step>)." },
+        "publish": { "enum": ["members", "domain", "public"], "description": "Who reads the changelog on Kaloko; domain and public need an admin on the service." }
+      }
+    },
+    "docs": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Visual changelog and docs settings (all optional).",
+      "properties": {
+        "dir": { "type": "string", "description": "Docs sources (default docs)." },
+        "changelog": { "type": "string", "description": "Changelog file (default CHANGELOG.md)." },
+        "style": { "enum": ["keep-a-changelog", "release-notes"] },
+        "version_source": { "enum": ["auto", "git-tag", "package.json", "release-please", "changesets", "semantic-release", "pyproject", "cargo", "gemspec", "manual"] },
+        "languages": { "type": "array", "items": { "type": "string" } },
+        "framework": { "enum": ["auto", "docusaurus", "vitepress", "mkdocs", "nextra", "plain"] },
+        "publish": { "enum": ["members", "domain", "public"], "description": "Who reads the changelog on Kaloko; domain and public need an admin on the service." },
+        "images": { "type": "object", "additionalProperties": false, "properties": { "viewport": { "type": "string" }, "locale": { "type": "string", "description": "reader (the reader's language) or a locale." } } }
+      }
+    },
     "record": {
       "description": "Recordings of walked steps (opt-in): true or step records each step from the previous screen to its capture; flow records the whole walk per locale with a chapter per step; failed keeps only steps that fail; false or off turns it off. Uploaded on Business and Enterprise.",
       "oneOf": [

package/schemas/run.v1.json

@@ -58,6 +58,14 @@
         },
         "archived": {
           "type": "boolean"
+        },
+        "product": {
+          "type": ["string", "null"],
+          "description": "Product the flow documents (scenario product tag, or the only product of the config)."
+        },
+        "module": {
+          "type": ["string", "null"],
+          "description": "Module of the product (scenario module tag)."
         }
       }
     },
@@ -267,6 +275,13 @@
         "number": {
           "type": "integer"
         },
+        "key": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Jira or Linear issue key (ENG-42) from the scenario, the branch or the pull request title."
+        },
         "url": {
           "type": [
             "string",
@@ -321,6 +336,18 @@
       },
       "description": "Steps whose revision differs from the parent version."
     },
+    "notes": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "description": "\"What changed\" notes of a design version (qawalk.version-notes.v1): summary and steps [{ step, title, locales, reason, changes, text }]; generated texts are { en, cs }, edited ones a string.",
+      "properties": {
+        "schema": { "const": "qawalk.version-notes.v1" },
+        "summary": { "type": ["string", "object", "null"] },
+        "steps": { "type": "array", "items": { "type": "object", "required": ["step"], "properties": { "step": { "type": "string" }, "reason": { "enum": ["new", "changed", "removed", "note"] }, "text": { "type": ["string", "object"] } } } }
+      }
+    },
     "draft": {
       "type": "object",
       "description": "Present when the manifest is a live draft, not a run."

package/schemas/scenario.v1.json

@@ -113,7 +113,7 @@
     "issue": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Ticket the scenario verifies. `number` alone resolves against the repository's remote.",
+      "description": "Ticket the scenario verifies. `number` alone resolves against the repository's remote; `key` names a Jira or Linear issue (ENG-42).",
       "properties": {
         "repo": {
           "type": "string",
@@ -123,6 +123,11 @@
           "type": "integer",
           "minimum": 1
         },
+        "key": {
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]{0,19}-[1-9][0-9]{0,8}$",
+          "description": "Jira or Linear issue key, e.g. ENG-42."
+        },
         "url": {
           "type": "string"
         },
@@ -166,6 +171,14 @@
       "$ref": "#/$defs/slug",
       "description": "Optional project this flow belongs to; overrides `project` from kaloko.config.yml and the repository name for its runs."
     },
+    "product": {
+      "$ref": "#/$defs/slug",
+      "description": "Product this flow documents (a key of `products:` in kaloko.config.yml). The visual changelog and docs of that product use its steps; with one product in the config, untagged flows belong to it."
+    },
+    "module": {
+      "$ref": "#/$defs/slug",
+      "description": "Module of the product (one of its `modules:`), for changelog and docs sections per module."
+    },
     "capture": {
       "$ref": "#/$defs/capture"
     }

package/skills/kaloko/SKILL.md

@@ -13,10 +13,14 @@ 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), and when implementing a
+  reference, checking implementation against it, importing Figma frames),
+  when looking for existing screens across flows, and when implementing a
   screen that has an approved design (read the step spec, build with its
   tokens, check drift), and when a step should be recorded on video or its
-  trace read (actions, requests, console).
+  trace read (actions, requests, console), and when a user-visible change
+  should land in the visual changelog (CHANGELOG.md with step references,
+  kaloko changelog draft, kaloko release) or a guide should show a step or
+  be written, translated or checked (kaloko docs check).
 ---
 
 # Kaloko
@@ -37,6 +41,15 @@ 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 the project keeps a visual changelog (`CHANGELOG.md`, `docs:` or
+  `products:` in the config) and the change is user-visible: the Unreleased
+  entry says it for people, with step references for the screens it changed
+  (`kaloko changelog draft`), and new scenarios carry `product:` (and
+  `module:`) when the config has products.
+- When the project keeps docs (`docs.dir`, a `docs/` folder with step
+  references) and the change is user-visible: the guides that show the changed
+  screens say what people see now, their translations follow, and
+  `kaloko docs check` reports no broken references or stale sections.
 - 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
@@ -44,7 +57,8 @@ the canvas, storage and collaboration are the service.
 - 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
-  version is published only when the person asked.
+  version is published only when the person asked, with notes that say what
+  changed and why (`kaloko share --notes-preview`, then `--notes`).
 
 ## You may do without asking
 
@@ -61,6 +75,10 @@ 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.
+Draft and edit the Unreleased section of the changelog (`kaloko changelog draft
+--apply`) and add step references to it and to guides. Write, translate and fix
+guides in the docs folder, run `kaloko docs check`, and export them for a docs
+site (`kaloko export --format …`) into a local folder.
 
 ## Ask first
 
@@ -70,7 +88,11 @@ replacing a CI workflow (`kaloko ci github|gitlab`), uploading with
 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, and
+(`kaloko prune --yes`), trashing someone else's run, archiving a scenario,
+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
+--release`), 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. Never approve a
@@ -120,6 +142,15 @@ they can do; never write secrets into the config, a scenario or a script.
   [reference/collaboration.md](reference/collaboration.md)
 - Reading runs, feedback and the inbox over MCP instead of the CLI:
   [reference/mcp.md](reference/mcp.md)
+- Filing a returned step or a failing criterion in Jira or Linear, issue keys in
+  branches, channels per project, and hosted runs of read-only scenarios on a
+  schedule (`kaloko issue`, `kaloko schedule`):
+  [reference/integrations.md](reference/integrations.md)
+- The visual changelog and guides with step references (`kaloko:<scenario>/<step>`):
+  drafting the Unreleased entry, Diátaxis templates, translations, stale sections
+  and `kaloko docs check`, training guides, exports, release tools in CI,
+  products, modules and versions, who reads it:
+  [reference/docs.md](reference/docs.md)
 - Refreshing a manual, course or product documentation from the newest
   captures (latest URLs, changed steps, webhooks, export):
   [reference/documentation.md](reference/documentation.md)
@@ -127,6 +158,10 @@ 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)
+- Bringing Figma frames in as design steps and the design reference
+  (`kaloko design import figma`), notes on what changed in a version, and
+  finding existing screens across flows (`kaloko screens`):
+  [reference/design.md#import-from-figma](reference/design.md#import-from-figma)
 - 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)

package/skills/kaloko/reference/design.md

@@ -95,6 +95,8 @@ color_schemes: [light, dark]
   on both sides is a conflict: name it with `--mine <step>` or `--theirs <step>`; never delete to resolve.
 - `kaloko share` on a design environment publishes a version of the flow (`v4 · 3 changed, 17 unchanged`).
   A version counts as a shared run. Publish when the person asks, not after every change.
+- Every version gets notes on what changed since the previous one; see
+  [What changed in a version](#what-changed-in-a-version).
 - Step status (`in progress`, `ready for review`, `ready for dev`) is set in the canvas or with MCP
   `set_step_status`; `ready for dev` notifies followers.
 - Set `KALOKO_AGENT=<your name>` so people see your writes as yours in presence, history and audit.
@@ -121,6 +123,59 @@ opens straight into the presentation of that step: share it with the person who
   relative links click through there too.
 - A link's query and hash travel to the next step (`../payment/index.html?plan=pro#card`): keep prototype state there.
 
+## What changed in a version
+
+When a version is published, Kaloko writes a short note per changed step against the previous version of the
+branch: a new or removed step, the text that changed (from the step spec), the viewports whose screenshot looks
+different, a new token set, or "looks the same; only the page code changed". Reviewers read it in the version's
+side panel and in the step detail; followers get the summary in their inbox.
+
+- Read what it would say before you publish: `kaloko share --notes-preview` (MCP `get_version_notes` with
+  `version: draft`).
+- Say why, not only what: write a file with a summary first and then `step-id: what changed and why` lines, and
+  publish with `kaloko share --notes notes.md` (or `--notes -` from standard input; MCP `publish_version` takes
+  `notes`). Your text replaces the generated one for the steps you name; the other steps keep theirs.
+- Fix them afterwards with MCP `set_version_notes` or `PUT …/scenarios/<id>/versions/v4/notes`. Plain language for
+  the people who review the design: what they will notice, not file names.
+
+## Import from Figma
+
+Teams whose design lives in Figma can make it the design reference without redrawing it:
+
+```bash
+export FIGMA_TOKEN=figd_…   # Figma → Settings → Security → Personal access tokens (file content: read-only)
+kaloko design import figma "https://www.figma.com/design/<key>/Shop?node-id=12-0" --scenario qa/flows/checkout.yml
+```
+
+- Frames match steps by name: a frame named after the step id or title, with a viewport or locale in it
+  (`Payment / mobile`, `payment@desktop`, `Košík [cs]`). Several frames of one step without a viewport in the name
+  take the viewport of their width. Anything else: `--map frames.json` (`{ "Frame 12": "payment" }`, or
+  `{ "step": "payment", "viewport": "mobile", "locale": "cs" }`, or `{ "skip": true }`). `--frames a,b` and
+  `--page <name>` narrow the import; `--dry-run` shows the matches without writing.
+- Each step gets `<step>/index.html` with the frame's PNG (1× and 2×) and, under it, the frame's text layers as
+  real text with Figma's typography and colors (`var(--token)` where a layer uses a variable or style), so
+  `kaloko spec` and `kaloko drift` have elements to compare. `figma.json` says which frame a page came from.
+- Variables become `tokens.json` (W3C DTCG; extra modes such as dark as mode groups); without variables, the color
+  and text styles the frames use. A `tokens.json` you wrote yourself stays unless you pass `--tokens write`.
+- Steps written by hand are not replaced without `--force`. Importing again replaces what the last import wrote;
+  unchanged frames give the same files, so the next version shows them unchanged.
+- No API token: export the frames from Figma as PNG (1× and 2×) or SVG into a folder and import the folder
+  (`kaloko design import figma ./export`); a `*.tokens.json` in it becomes the token set.
+- Then walk and share as usual, or add `--publish` (start, walk and share in one go). Once a person accepts the
+  version, set it as the design reference: implementation runs with `packs: [design]` are checked against the
+  frames (`design_pixels`) and the text styles and tokens (`kaloko drift`).
+- One way only: prototype links, components, auto layout and interactions do not come over, and nothing goes
+  back to Figma. A frame wider or narrower than its viewport is compared as it is; draw a frame per viewport for a
+  clean pixel comparison.
+
+## Screen library
+
+The newest screenshot of every step across the organization's flows, searchable: `/<org>/screens` on the service,
+`kaloko screens [words]` (`--project`, `--locale`, `--viewport`, `--status fail`, `--designs` for design versions,
+`--json`), MCP `search_screens`. Search matches step and flow titles, ids, paths, URLs, page titles and the H1,
+without caring about diacritics. Use it to find where a pattern is already used before designing a new one, and
+link the screens you reuse in your notes.
+
 ## References
 
 - The design reference is an accepted version: `kaloko reference --design --version 4` (a person accepts the