kaloko 0.5.2 → 0.7.0

package/README.md

@@ -8,8 +8,8 @@ e-mail of the flow, checks the criteria and lays the whole flow out on a
 canvas: screens, branches, locales and evidence. People review and approve it
 there, and the newest captures double as documentation.
 
-- Product and guides: <https://kaloko.app>
-- Service (organizations, shared canvases, reviews): <https://kaloko.app>
+- Product, pricing and the service (organizations, shared canvases, reviews): <https://kaloko.app>
+- Guides: <https://kaloko.app/guides>
 
 Pages are walked in Chromium, WebKit and Firefox, on phone, tablet and
 desktop presets, in light and dark mode. Native apps too: Android, iOS,
@@ -201,6 +201,18 @@ 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.
 
+To see what moved, compare a step with the accepted run side by side, as a
+pixel diff, with *Swipe* or with *Onion skin*; `G` shows one step in every
+locale and viewport at once. Comments can carry a box, an arrow or a line
+drawn on the screenshot. On Business and Enterprise an accepted run has a
+signed acceptance record (who approved what and when, criteria results,
+screenshot hashes) as PDF and JSON:
+
+```bash
+npx kaloko signoff <run-id> --out handover/   # download and check the record
+npx kaloko signoff --verify record.pdf         # check one someone handed you; no token needed
+```
+
 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
@@ -208,7 +220,8 @@ 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.
+find the clocks, ads and carousels worth ignoring, and `kaloko stability --pull`
+brings in the regions reviewers marked on kaloko.app.
 
 ## A changelog with pictures
 
@@ -236,7 +249,63 @@ 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`.
+`kaloko.config.yml`; `npx kaloko products sync` puts them on Kaloko before the
+first release, and Products in the app's menu lists each with its newest
+version, changelog and docs (`npx kaloko products list` in the terminal).
+
+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. Both come with the Team plan and up.
+
+## 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: 2,000 pages a
+month, Enterprise: 10,000):
+
+```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)
 
@@ -244,8 +313,8 @@ Design the screens of a flow as live HTML with your own agent and skills, in the
 and QA use. A design environment (`kind: design`, a folder of steps) is walked and synced into a shared draft the
 team sees live; `kaloko share` there publishes a version of the flow (unchanged steps are stored once). An
 accepted version becomes the design reference, and `packs: [design]` checks every implementation run against
-it (pixels, structure, tokens, contrast). See `skills/kaloko/reference/design.md`, `docs/GLOSSARY.md` and
-`docs/SURFACES.md`.
+it (pixels, structure, tokens, contrast). Details: `skills/kaloko/reference/design.md` in the package and the
+[design guides](https://kaloko.app/guides/design-with-your-agent).
 
 ```bash
 npx kaloko start --scenario qa/flows/checkout.yml --env design
@@ -266,6 +335,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.2",
+  "version": "0.7.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/run.v1.json

@@ -275,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",
@@ -329,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"
         },

package/skills/kaloko/SKILL.md

@@ -13,12 +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), 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.
+  kaloko changelog draft, kaloko release) or a guide should show a step or
+  be written, translated or checked (kaloko docs check).
 ---
 
 # Kaloko
@@ -44,6 +46,10 @@ the canvas, storage and collaboration are the service.
   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
@@ -51,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
 
@@ -69,7 +76,11 @@ 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.
+--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
+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
 
@@ -80,7 +91,10 @@ 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,
-recording a release (`kaloko release`) or asking to publish a changelog, and
+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
@@ -106,13 +120,12 @@ they can do; never write secrets into the config, a scenario or a script.
 - 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, thresholds, the vision evaluator and its reasons, reading
-  results: [reference/evaluation.md](reference/evaluation.md)
+- Choosing playwright, agent or manual per step, driving the shared
   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)
+- Evaluation, JEV thresholds, the vision evaluator and its reasons, reading
+  results: [reference/evaluation.md](reference/evaluation.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)
 - Video of a step or a whole flow, traces (actions, requests, console) and the
@@ -120,19 +133,24 @@ they can do; never write secrets into the config, a scenario or a script.
   [reference/recording.md](reference/recording.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:
   [reference/environments.md](reference/environments.md)
 - Sharing, review mode and approvals carried over unchanged steps, reviewer
-  feedback, mentions, inbox, verdicts and baselines, and cleaning up runs
+  feedback, mentions, inbox, verdicts and baselines, compare views, the
+  signed acceptance record (`kaloko signoff`), 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)
+- 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, templates for entries, client release notes and
-  how-tos, products, modules and versions, who reads it:
+  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 (`kaloko products sync|list`), 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):
@@ -141,6 +159,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

package/skills/kaloko/reference/docs.md

@@ -82,6 +82,124 @@ A how-to guide (`docs/how-to/pay-with-apple-pay.md`):
 Rules: write for the person using the product; one change per line; before/after pictures for changes people see;
 no internal names, prices or numbers you cannot show.
 
+## Living docs
+
+Guides live in the docs folder (`docs.dir`, default `docs/`; per product `products.<p>.docs.dir`), sorted the
+Diátaxis way. Pick the folder by what the reader wants, not by the feature:
+
+| Folder | The reader wants | Shape |
+|---|---|---|
+| `tutorials/` | to learn by doing, start to finish | one path that always works, a result at the end |
+| `how-to/` | to get one task done | numbered steps, one picture per step people look for |
+| `reference/` | to look a fact up | tables and lists, no story |
+| `explanation/` | to understand why | prose, few pictures |
+
+`index.md` (or `README.md`) is the page of its folder. Front matter is optional: `title` (else the first `# `
+heading), `order` (sidebar position). `kaloko init --docs=full` creates the folders with a template in each
+README (inside a comment, so it never shows).
+
+A tutorial:
+
+```markdown
+---
+title: Your first order
+order: 1
+---
+# Your first order
+
+In ten minutes you will have placed an order and seen it in your account.
+
+1. Open the shop and put a tea in the cart.
+   ![Cart](kaloko:checkout/cart)
+2. Choose **Checkout** and pay with a test card.
+   ![Payment](kaloko:checkout/payment)
+
+You have placed your first order. Next: [track it](../how-to/track-an-order.md).
+```
+
+A reference page:
+
+```markdown
+# Order states
+
+| State | What it means |
+|---|---|
+| Paid | The payment went through; the order waits for packing. |
+| Shipped | The parcel left the warehouse. |
+```
+
+An explanation: plain paragraphs that say why ("Card payments are confirmed the next morning, so a cancelled order
+costs the customer nothing"), with a picture only when it shows the point.
+
+Link pages with relative `.md` links (`[track it](../how-to/track-an-order.md)`); Kaloko and every export rewrite
+them. Keep one task per how-to; split a page that needs two "and then" headings.
+
+### Training guides
+
+A how-to or tutorial is also a walkthrough: on Kaloko, "Walk through it step by step" shows one step at a time,
+full screen, with the step's words as the caption, and readers tick "I tried it". Each list item (or paragraph)
+with a picture becomes one step; a picture on its own line belongs to the words above it; a before/after pair shows
+the after. So for guides people train with: one action per item, the picture right under it, words that make sense
+without the paragraphs around them.
+
+### Translations
+
+Translations sit next to the original: `pay.md` and `pay.cs.md`. `docs.languages: [en, cs]` names the languages;
+the first is the language of the originals. Pictures follow the language of the text (a Czech page shows Czech
+screens) unless a reference names `locale=`.
+
+When you change an original, update its translations in the same change. Translate the words, keep the step
+references as they are. To say which version of the original a translation follows, put the first characters of
+the original's SHA-256 in the translation's front matter (`source_hash: 1a2b3c4d`; `shasum -a 256 pay.md`);
+without it, `kaloko docs check` compares git dates. It reports missing and outdated translations as warnings.
+
+### Stale sections and `kaloko docs check`
+
+`kaloko docs publish` sends the folder to Kaloko as the docs of `latest` (`--version 2.4.0` for a release;
+`kaloko release` publishes the folder for its version by itself). When a page's text changes, Kaloko remembers the
+screen behind each of its references. When an accepted run later shows a different screen, the section reads
+"the screen changed in 2.4 — check the text" for the people who write the docs.
+
+Before a pull request that changes screens, and in CI:
+
+1. `kaloko docs check` (add `--json` to read it as data). Errors: broken references, steps the scenario files do
+   not have, references without an accepted picture, stale sections. Warnings: missing or outdated translations,
+   user-visible changelog items without a picture (mark one with `<!-- no picture -->` when there is nothing to
+   show). Exit code 1 on errors; `--strict` also on warnings.
+2. For each stale section, open the step (`resolve_step_image` or the link on the page), compare, and rewrite the
+   words that no longer fit. Editing the text clears the note at the next `kaloko docs publish`.
+3. If the text still fits, say so to the person; with their go-ahead `kaloko docs publish --reviewed` clears the
+   notes without a text change. Never use `--reviewed` to silence notes you have not read.
+
+MCP: `docs_check` (the same report for the published docs), `get_docs` (the sidebar, or a page with its sections,
+stale sections and training steps).
+
+### Exports
+
+`kaloko export --format md|docusaurus|vitepress|mkdocs|html|pdf|json [--product p] [--version v] [--lang cs]`
+writes the docs and the changelog with the pictures as files: Markdown with an `assets/` folder (any static site),
+a Docusaurus, VitePress or MkDocs folder with sidebars and front matter, offline HTML, a PDF (printed by the
+browser), or the changelog as JSON (`schemas/changelog.v1.json`). `--local` exports the files in the repository
+instead of what was published; `--what docs|changelog` exports one of them. The docs and changelog pages offer the
+same downloads. An existing docs site keeps its own build: export into its folder and commit the result, or run the
+export in its CI.
+
+### Release tools in CI
+
+When release-please, changesets or semantic-release makes the releases, Kaloko follows them:
+`kaloko ci github --release` writes `.github/workflows/kaloko-release.yml`, which runs
+`kaloko release <version> --no-write` whenever a GitHub release is published (all three tools publish one). It
+reads the entry the tool wrote, records the release with its pictures and publishes the docs of that version.
+`kaloko ci github --release --snippet` prints the step to put after the tool's own step instead (release-please:
+`if: steps.release.outputs.release_created`; changesets: `if: steps.changesets.outputs.published == 'true'`;
+semantic-release: right after `npx semantic-release`). On GitLab, call `kaloko release <version> --no-write` in
+the release job. Ask before writing a workflow.
+
+### "What's new" e-mail
+
+Readers subscribe per product on its changelog or docs page (Business). When a release is recorded, they get its
+entry with pictures in their language. Nothing to do in the repository beyond writing the entry for people.
+
 ## Products, modules and versions
 
 Without `products:` in `kaloko.config.yml` the project is the product and `CHANGELOG.md` in the root is its
@@ -113,15 +231,23 @@ reads its entry and never rewrites the file; put your draft into the pull reques
 
 `kaloko doctor` warns when a product's version cannot be read or a scenario names no product while several exist.
 
+A product shows in the app (Products in the main menu, `/<org>/products`) once it is on Kaloko. `kaloko release` and
+`kaloko docs publish` put it there; to put the products of the config there before their first release, run
+`kaloko products sync` (`--product p` for one, `--dry-run` to see what it would send). It records no release, and
+`publish:` still needs an admin of the product's projects. `kaloko products list` shows the products on Kaloko with
+their newest version and docs, and names those of the config that are not there yet. After adding or renaming a
+product in the config, run `kaloko products sync` and say so in your summary.
+
 ## Readers
 
-The changelog page (`/<org>/products/<product>/changelog`, or `/<org>/projects/<project>/changelog`) is read by
-everyone who sees one of the product's projects, guests included. An admin of those projects may open it to
+The changelog page (`/<org>/products/<product>/changelog`, or `/<org>/projects/<project>/changelog`) and the docs
+(`…/docs`) are read by everyone who sees one of the product's projects, guests included. An admin of those projects may open it to
 readers from the organization's verified domains or publish it (`/p/<org>/<product>/changelog` with an Atom feed;
 not indexed until the organization allows it). `publish:` in the config only asks for it; an admin confirms on the
 page. Never publish without the person asking.
 
 ## MCP
 
-`get_changelog` (releases with entries; `resolve: true` adds the pictures), `draft_changelog_entry` (the service's
-half of a draft: changed screens with before/after references), `resolve_step_image` (one reference).
+`list_products` (the products the caller reads, with the newest release, docs and readers), `get_changelog` (releases with entries; `resolve: true` adds the pictures), `draft_changelog_entry` (the service's
+half of a draft: changed screens with before/after references), `resolve_step_image` (one reference),
+`docs_check` (what needs attention in the published docs), `get_docs` (the docs, or one page).