kaloko 0.3.0 → 0.4.1

package/README.md

@@ -1,12 +1,12 @@
 # Kaloko
 
-Acceptance QA walkthroughs rendered as a shareable flow canvas.
+See what your agent built, on one canvas, and sign it off.
 
-Your coding agent (Claude Code, Codex or any LLM with a shell) runs QA from
-your acceptance plan with the `kaloko` skill. Kaloko captures every screen and
-e-mail of the flow, checks the criteria and builds a canvas that shows the
-whole flow (screens, branches, locales, evidence) for review, sign-off and
-living documentation.
+Your coding agent (Claude Code, Codex or any LLM with a shell) walks your
+acceptance plan with the `kaloko` skill. Kaloko captures every screen and
+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>
@@ -32,9 +32,9 @@ after `npm update kaloko` to refresh the skill.
 
 ## Then ask your agent
 
-With the skill installed you do not type the commands below; the agent does.
-It writes the acceptance plan and the scenario from the task, walks the
-screens, evaluates, shares the canvas and later processes reviewers' feedback.
+With the skill installed, the agent types the commands below, not you. It
+writes the acceptance plan and the scenario from the task, walks the screens,
+evaluates, shares the canvas and later works through what reviewers said.
 For example:
 
 > Read the task in docs/tasks/TASK-123, write its acceptance plan and a Kaloko
@@ -66,8 +66,8 @@ token, environment URL, evaluator key), `npx kaloko doctor` says what to fix.
 
 ## Design (Kaloko Design)
 
-Design the screens of a flow as live HTML with your own agent and skills, in the same scenario development and
-QA use. A design environment (`kind: design`, a folder of steps) is walked and synced into a shared draft the
+Design the screens of a flow as live HTML with your own agent and skills, in the same scenario that development
+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
@@ -75,11 +75,29 @@ it (pixels, structure, tokens, contrast). See `skills/kaloko/reference/design.md
 
 ```bash
 npx kaloko start --scenario qa/flows/checkout.yml --env design
+npx kaloko design lint                    # portable HTML: works on the canvas, from disk and in other tools
 npx kaloko walk && npx kaloko sync        # only changed steps render and travel
 npx kaloko share --name "Checkout v2"     # a version of the whole flow
 npx kaloko reference --design --version 2 # after the team accepted it
 ```
 
+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`.
+
+## Your data is yours: formats
+
+Nothing in Kaloko is stored in a format only Kaloko can read. Every export opens from disk without it:
+
+| Export | Command | Formats |
+|---|---|---|
+| Design version | `npx kaloko export --design [--version n] --out v2.zip` | HTML, CSS, JS, fonts and images in the design folder layout; `tokens.json` (W3C DTCG); `scenario.yml` (`qawalk.scenario.v1`); screenshots (WebP); `index.html` start page |
+| Live files (handoff) | `npx kaloko export --live [--version n] --out design/` | the design folder as written |
+| Shared run | `npx kaloko export --run <id>` | zip with `run.json` (`qawalk.run.v1`), screenshots and HTML snapshots, live HTML of design steps, comments and verdicts, and `index.html`: the canvas, offline |
+| Documentation captures | `npx kaloko export --scenario <id>` | newest image and HTML of every step, `index.json` |
+
+The schemas of these formats ship with the package (`schemas/`).
+
 ## Configuration and secrets
 
 Project configuration is `kaloko.config.yml` in the repository root:

package/package.json

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

package/schemas/scenario.v1.json

@@ -487,6 +487,8 @@
             "link_matches",
             "http_status",
             "link_home",
+            "links_ok",
+            "hreflang_pairs",
             "app_touch_targets",
             "app_no_truncation",
             "app_no_crash",
@@ -508,10 +510,12 @@
           ]
         },
         "selector": {
-          "type": "string"
+          "type": "string",
+          "description": "CSS selector; links_ok: the links to check (default a[href])."
         },
         "pattern": {
-          "type": "string"
+          "type": "string",
+          "description": "Regex; links_ok: link paths to skip."
         },
         "attr": {
           "type": "string"
@@ -526,17 +530,23 @@
         },
         "min": {
           "type": "integer",
-          "minimum": 0
+          "minimum": 0,
+          "description": "count: at least; http_status: lowest status; hreflang_pairs: languages required (default 2)."
         },
         "max": {
           "type": "integer",
-          "minimum": 0
+          "minimum": 0,
+          "description": "count: at most; http_status: highest status; perf_*: the limit; links_ok: links checked per page (default 100)."
         },
         "ratio": {
           "type": "number",
           "minimum": 0,
           "description": "design_pixels: maximum share of differing pixels (default 0.03)."
         },
+        "follow": {
+          "type": "boolean",
+          "description": "links_ok: follow links even when neither the environment nor the scenario is readonly (GET from an isolated copy of the session; links that look like actions are never followed)."
+        },
         "flags": {
           "type": "string",
           "pattern": "^[imsu]{0,4}$",

package/skills/kaloko/SKILL.md

@@ -31,9 +31,10 @@ the canvas, storage and collaboration are the service.
   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.
+- 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.
 
 ## You may do without asking
 
@@ -84,7 +85,12 @@ they can do; never write secrets into the config, a scenario or a script.
   [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)
+  view, presenting the prototype, exports, bringing your own design skill):
+  [reference/design.md](reference/design.md)
+- Writing design pages that work on the live step, from disk and in other
+  tools (relative URLs, no CDNs, state in the URL, deterministic content,
+  links between steps; what `kaloko design lint` checks):
+  [reference/portable-html.md](reference/portable-html.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 ✕.

package/skills/kaloko/reference/acceptance.md

@@ -187,6 +187,27 @@ button styled uppercase reads `VYTVOŘIT`. Add `flags: i` to ignore case
 white-label check for `vyvolej` also matches the Czech verb "Vyvolej si";
 anchor it (`vyvolej\.to`).
 
+Two checks need the network and run next to the capture, once per page:
+
+- `links_ok`: every same-origin link (`selector`, default `a[href]`) answers
+  below 400 after redirects. `max` caps the links per page (default 100),
+  `pattern` skips matching paths. Redirects are listed in the evidence.
+  Links are followed only on a readonly environment or scenario; elsewhere
+  the criterion is not evaluated unless the check sets `follow: true`. Links
+  that look like actions (log out, unsubscribe, delete, remove, tokens,
+  switching organization) are never requested.
+- `hreflang_pairs`: at least `min` languages (default 2); the page's own
+  language points to the page itself; every other version answers 200
+  without a redirect and links back. This is what search engines require
+  of hreflang; a count of `link[hreflang]` does not prove it.
+
+Both are GETs from a separate request context that starts with a copy of
+the walk's cookies and the environment's gate and never writes back (a
+`?lang=` link cannot switch the language of the next step). They are cached
+per environment, locale and sign-in state, so a stack of hundreds of pages
+fetches its shared navigation once. A recheck
+from stored HTML keeps their last result; capture again to refresh them.
+
 Describe every relevant variant as nodes and `alt` edges, even when a given
 run covers only part of it. Decisions are `kind: decision` nodes.
 

package/skills/kaloko/reference/collaboration.md

@@ -1,7 +1,7 @@
 # Collaboration: share, feedback, inbox
 
-A run becomes useful when the people who decide can see it. The loop that
-works for teams using Kaloko:
+A run is only worth something once the people who decide have seen it. The
+loop teams use:
 
 1. **Share the run** (`kaloko share`, tester token, after asking). The
    command prints the canvas URL.

package/skills/kaloko/reference/design.md

@@ -37,9 +37,14 @@ design/
   images, fonts, module imports, `fetch('./fixtures/x.json')`). Links to other steps are not files it needs.
 - Live steps run sandboxed on their own origin with `connect-src 'self'`: no real APIs. Use JSON fixtures in
   the bundle.
-- Prototype links: `<a data-qawalk-go="payment">` moves the canvas to that step, whatever the `href` says.
+- Links between steps are plain relative links to the page: `<a href="../payment/index.html">`. The canvas
+  follows them; `data-kaloko-go="payment"` (or `data-qawalk-go`) moves to that step whatever the `href` says.
 - Reference token values as CSS custom properties (`var(--color-accent)`), so the inspector and the token
   check see where values come from.
+- Write pages by the portable HTML rules ([portable-html.md](portable-html.md)): relative URLs only, bundled
+  fonts, no CDNs, state in the URL instead of storage, deterministic content, viewport meta and `lang`.
+  `kaloko design lint` checks the folder; `kaloko sync` runs it first and stops on errors (things that break on
+  the live step), warnings are printed.
 
 ## Sync and publish
 
@@ -62,6 +67,19 @@ design/
 4. Change what the comments ask, sync again, then answer in the comment thread (MCP `add_draft_comment`).
 5. When the person is happy, `kaloko share --name "…"` publishes a version.
 
+## Present the prototype
+
+The canvas plays design steps full screen: *Prototype* in the top bar or the step detail, or `P`. Each step runs as
+its live page in a device frame (phone for mobile viewports, a window for desktop; switchable), clicks on links and
+`data-kaloko-go` move between steps, `←` `→` walk the flow, `Esc` leaves. The address (`#present=<step>&vp=mobile`)
+opens straight into the presentation of that step: share it with the person who reviews.
+
+- Live pages need the user-content origin of the service; where it is not available (a self-hosted instance
+  without it, a step never rendered live) the presentation shows the screenshots.
+- From the local preview and an offline export, the steps open from the run's merged folder (`live/site/`), so plain
+  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.
+
 ## References
 
 - The design reference is an accepted version: `kaloko reference --design --version 4` (a person accepts the
@@ -78,6 +96,18 @@ Development builds from the design reference:
   page structure and open comments; `list_step_changes` names the steps that changed since the last reference.
 - Translate to the project's stack with the project's own skills; keep the step ids and the token names.
 
+## Your data is yours
+
+Everything exports in open formats, readable without Kaloko:
+
+| What | Command | Contents |
+|---|---|---|
+| a design version (or `--draft`, default the design reference) | `kaloko export --design [--version n] --out dir/` or `--out v4.zip` | the live files in the folder layout, `tokens.json` (DTCG), `scenario.yml` (`qawalk.scenario.v1`), `screenshots/<step>/<locale>/<viewport>.webp`, `kaloko.json` (what is where) and `index.html`, a start page that opens from disk |
+| the live files only (the handoff) | `kaloko export --live [--version n] --out design/` | the design folder as the designer wrote it |
+| a shared run | `kaloko export --run <id>` | `run.json`, every capture, the live HTML of design steps (per revision and merged in `live/site/`), comments and verdicts, and `index.html`: the canvas, offline from `file://` |
+
+When someone asks for the design or the evidence outside Kaloko, export; do not screenshot the canvas.
+
 ## Tokens
 
 - The set is W3C DTCG. Both value styles are read: strings (`"#2E6BFF"`, `"16px"`) and the current format's

package/skills/kaloko/reference/evaluation.md

@@ -22,9 +22,8 @@ evaluating the same capture again costs nothing. `evaluators.jev.hosted: false`
 When neither is available, or the allowance is used up, semantic criteria stay `not_evaluated`; say so in the
 report with the reason `kaloko evaluate` gives.
 
-Results are cached by content hash, so re-running is cheap. The default
-evaluator is text-only and most accurate in English; it is weak at numbers,
-which is why those are deterministic.
+The default evaluator is text-only and most accurate in English. It is weak
+at numbers, which is why those are checked deterministically.
 
 When a criterion comes back `needs_review`, read the reduced state the
 evaluator saw (`steps/<node>/<locale>/<viewport>.capture.json`, key `state`)

package/skills/kaloko/reference/portable-html.md

@@ -0,0 +1,92 @@
+# Portable interactive HTML
+
+Design steps are live pages. The same files have to work in three places:
+
+- **on the live origin** of the canvas (`<revision>.kaloko-usercontent.com`): a sandboxed frame with an opaque origin and
+  `Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; connect-src 'self'; frame-src 'none';
+  worker-src 'none'; form-action 'none'` (no popups, no modals, no service workers);
+- **from disk** (`file://`): the local preview, `kaloko export --design`, and anyone who unzips an export;
+- **in another tool**: the export is the handoff and the way out of Kaloko.
+
+`kaloko design lint` checks a design folder against the rules below; `kaloko sync` runs it first and stops on errors
+(`--no-lint` skips it, `kaloko walk` prints a summary). Errors break for certain on the live step; warnings make the
+prototype fragile or the captures unstable. `kaloko design lint --all` also lists information, `--strict` fails on
+warnings, `--json` gives every finding with file, line, rule and fix.
+
+## Files
+
+- Everything a page needs is in the design folder, referenced with **relative paths** (`../_shared/app.css`). No
+  `https://`, no protocol-relative `//cdn…`, no paths starting with `/` (on the live origin `/` is the origin root, from
+  disk it is the disk root). Errors: `external-url`, `root-relative`, `outside-folder`, `missing-file`.
+- **No CDNs.** Download libraries into `_shared/` and link them relatively. Fonts are bundled as **woff2**, subset to
+  the characters used, with `@font-face` in the shared CSS; Google Fonts links do not load.
+- Only bundle file types (html, css, js, mjs, json, svg, woff2, woff, png, jpg, webp, avif, gif, mp4, webm, txt).
+  Convert TTF/OTF fonts and other formats (`file-type`).
+- **Size budget:** a file over 1 MB or a step over 5 MB (with the shared files) warns (`large-file`); 10 MB per file
+  and 40 MB per step are the limits (`too-large`). Images as webp/avif at the size shown.
+
+## Links between steps
+
+- Link steps with **plain relative links to the page itself**: `<a href="../payment/index.html">`, from a locale page
+  `../../payment/cs/index.html`. A link to a folder (`../payment/`) opens nothing from disk or a zip
+  (`directory-link`); a link to a page that does not exist warns (`broken-link`).
+- The canvas follows such links in the presentation and the Live view, and `data-kaloko-go="payment"` (or the older
+  `data-qawalk-go`) moves to a step whatever the `href` says. Keep a real `href` next to it so the page also works
+  from disk.
+- No `target="_blank"`, `window.open`, `top.location` (`new-window`, `top-navigation`): the frame may not open
+  windows or navigate the canvas.
+- Forms do not submit (`form-action 'none'`): handle `submit` in a script (`event.preventDefault()`) and go on with a
+  link or `data-kaloko-go` (`form-action`).
+
+## State and data
+
+- **State lives in the URL**, not in storage: `localStorage`, `sessionStorage`, IndexedDB and cookies throw in the
+  sandboxed frame and are empty for every other viewer (`storage`). Use `location.hash` or the query
+  (`?plan=pro#card`): a link's query and hash travel to the next step in the presentation, and work from disk.
+  Wrap any storage access you keep in `try/catch` with a fallback.
+- **No network:** real APIs, `XMLHttpRequest`, `WebSocket`, `EventSource` do not connect (`websocket`). Put data in
+  JSON fixtures of the bundle and `fetch('./fixtures/cart.json')`.
+- **No code from strings:** `eval`, `new Function`, `setTimeout('…')` are blocked (`eval`). No service workers
+  (`service-worker`), no iframes, `object` or `embed` (`embedded-frame`). `alert`, `confirm` and `prompt` are blocked
+  (`modal`): use an in-page `<dialog>`.
+
+## Deterministic content
+
+Captures are cached by content and compared in pixels. A page that changes on every render makes unchanged steps look
+changed (`nondeterministic`):
+
+- fixed dates (`new Date('2026-01-15T10:00')`), no `Date.now()` or `new Date()` for visible text;
+- fake data from a seeded generator, not `Math.random()` or `crypto.randomUUID()`;
+- animations that end, or none at the moment of capture; content that does not depend on load timing.
+
+## Document basics
+
+Every page starts like this (`doctype`, `charset`, `viewport-meta`, `lang`, `title`):
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Payment · Checkout</title>
+  <link rel="stylesheet" href="../_shared/app.css">
+</head>
+```
+
+- Images have `alt` (`alt=""` for decoration) (`img-alt`); real buttons, labels for fields, one `<h1>`, landmarks.
+- Respect `prefers-reduced-motion` when anything animates (`reduced-motion`):
+  `@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation: none !important; transition: none !important } }`
+- The mobile viewports render at their real width: the viewport meta and fluid layout matter.
+
+## Tokens
+
+- `tokens.json` (W3C DTCG) in the folder root; values as **CSS custom properties** in the shared CSS
+  (`--color-accent: #2e6bff`) and used with `var(--color-accent)`, so the inspector names them and `kaloko tokens check`
+  sees raw values (`tokens-unused`, `no-tokens`).
+- Name custom properties after the token path with dots as dashes (`color.accent` → `--color-accent`).
+
+## Done means
+
+`kaloko design lint` shows no error and no warning you cannot explain, the pages open from the folder by
+double-click and click through, and `kaloko walk` renders the same in every viewport.

package/src/cli.mjs

@@ -12,7 +12,8 @@ import { startBrowser, stopBrowser, connectBrowser, currentPage, launchEphemeral
 import { captureStep, captureCrop, captureOptions, acceptDialogs } from './lib/capture.mjs'
 import { observeConsole } from './lib/console.mjs'
 import { mailClient, waitForMessage, recipient, readMessageFile } from './lib/mail.mjs'
-import { newContext, accountFor, gateHeaders, gateOrigins, originMatcher } from './lib/access.mjs'
+import { newContext, accountFor, gateHeaders, gateOrigins, originMatcher, gateForRequests } from './lib/access.mjs'
+import { configureGate } from './lib/linkcheck.mjs'
 import { rememberEnvironment } from './lib/secrets.mjs'
 import { evaluateRun, semanticPrefetch } from './lib/evaluate.mjs'
 import { buildManifest, writePreview } from './lib/build.mjs'
@@ -32,6 +33,8 @@ import { htmlViewAllowed } from './lib/htmlview.mjs'
 import { service } from './lib/service.mjs'
 import { walkDesign, syncDesign, publishVersion, historyCmd, referenceCmd, tokensCmd, exportLive, localRevisions, branchCmd, uploadBlobs } from './lib/design-cli.mjs'
 import { designDir, readBase, headKey } from './lib/design.mjs'
+import { lintDesign, formatLint } from './lib/design-lint.mjs'
+import { exportDesign } from './lib/design-export.mjs'
 import { driverFor, isApp, pngSize, ocr as ocrImage } from './lib/apps/drivers.mjs'
 import { captureApp } from './lib/apps/capture.mjs'
 import { readTree, flatten } from './lib/apps/tree.mjs'
@@ -121,7 +124,8 @@ Results
                                     Semantic evaluator vs human labels: precision/recall per criterion at the
                                     configured thresholds and suggested thresholds (labels from a golden file or
                                     from reviewers' criterion verdicts in the service)
-  export [--run id] [--out file.zip]  Download a shared run (run.json + files) as a zip before it expires
+  export [--run id] [--out file.zip]  Download a shared run as a zip before it expires: run.json, every file, the live
+                                    HTML of design steps and index.html, the canvas that opens offline from disk
   export --scenario <id> [--accepted] [--out dir] [--locales l] [--viewports v]
                                     Newest capture of every step as steps/<step>/<locale>/<viewport>.<ext> plus
                                     index.json (documentation layer, Business plan); unchanged files are skipped
@@ -134,8 +138,12 @@ Design (environments with kind: design; live HTML steps in a folder)
   start --scenario <file> --env <design env>   A run of the design folder (same scenario as development and QA)
   walk [--steps a,b] [--no-cache]   Render the steps; unchanged revisions reuse their captures
   status                            Per step: synced, changed here, changed in the draft, conflict; step status
-  sync [--pull|--push] [--branch b] [--mine a,b|--theirs a,b]
+  sync [--pull|--push] [--branch b] [--mine a,b|--theirs a,b] [--no-lint]
                                     Exchange revisions with the shared draft; only changed steps and missing files travel
+                                    Lints the folder first: errors (things that break on the live step) stop the push
+  design lint [--env e | --dir design/] [--scenario file] [--all] [--strict] [--json]
+                                    Check the folder against the portable HTML rules (relative URLs, no CDNs, no storage,
+                                    deterministic content, viewport, lang, links that also work from disk); --strict fails on warnings
   share [--name <text>] [--branch b]  Publish the draft as a version of the flow (a run): "v4 · 3 changed, 17 unchanged"
   history [--scenario id] [--step id] [--locale l] [--json]
                                     Versions of the flow; revisions of a step with who (person or agent) and when
@@ -149,6 +157,9 @@ Design (environments with kind: design; live HTML steps in a folder)
                                     Live files of a version (default: the design reference) into a folder: the handoff
   export --live --views --run <id> [--viewport desktop] [--out design/]
                                     Fork into a draft: the HTML views of an app run become design steps (experimental)
+  export --design [--version n|--draft|--run id] [--out dir|file.zip]
+                                    A design version in open formats: HTML + assets, tokens.json (DTCG), scenario.yml,
+                                    screenshots and an index.html that opens from disk (default: the design reference)
 
 Common options: --run <id|dir> (or KALOKO_RUN)  --config <file>   KALOKO_AGENT=<name> labels writes by an agent
 `
@@ -654,6 +665,7 @@ const commands = {
       } finally { await enc?.close().catch(() => {}) }
       return
     }
+    configureGate(await gateForRequests(env, { root }))
     let conn = await connectBrowser({ root, config, env })
     let ephemeral = null
     let page
@@ -709,12 +721,15 @@ const commands = {
     const { config, root, run, scenario, env } = await runContext(args)
     if (env.kind === 'design') {
       await walkDesign({ config, root, run, scenario, env, pick: list(args.steps), locales: list(args.locales) || run.meta.scope.locales, viewports: scopeViewports(run, list(args.viewports)), say, noCache: !!args['no-cache'] })
+      const lint = await lintDesign({ dir: designDir(env, root), scenario })
+      if (lint.errors || lint.warnings) say(`\nPortable HTML: ${lint.errors} error(s), ${lint.warnings} warning(s); kaloko design lint lists them${lint.errors ? ' (errors stop kaloko sync: they break on the live step)' : ''}.`)
       return
     }
     if (isApp(scenario.platform)) return walkApp({ config, root, run, scenario, env, args })
     const pick = list(args.steps)
     const locales = list(args.locales) || run.meta.scope.locales
     // --ephemeral: an own browser (own cookies and tabs) even when the shared one runs, so runs can walk in parallel
+    configureGate(await gateForRequests(env, { root }))
     const conn = args.ephemeral ? null : await connectBrowser({ root, config, env })
     const releaseLock = conn ? await acquireWalkLock({ root, config, env, run: run.meta.id }).catch(async (e) => { await conn.browser.close(); throw e }) : null
     const ephemeral = conn ? null : await launchEphemeral(config)
@@ -1026,9 +1041,33 @@ const commands = {
   async sync (args) {
     const { config, root, run, scenario, env } = await runContext(args)
     const client = service(config)
+    if (env.kind === 'design' && !args.pull && !args['no-lint']) {
+      // what renders locally may still break on the live step (CSP, sandbox): say so before anything is pushed
+      const lint = await lintDesign({ dir: designDir(env, root), scenario })
+      if (lint.errors || lint.warnings) say(formatLint(lint, { max: 15 }) + '\n')
+      if (lint.errors) throw new UserError(`${lint.errors} error(s) above break the design on the live step; fix them, or sync with --no-lint to push anyway.`)
+    }
     await syncDesign({ config, root, run, scenario, env, client, args, say, push: !args.pull, pull: !args.push, render: (steps) => walkDesign({ config, root, run, scenario, env, pick: steps, locales: run.meta.scope.locales, viewports: run.meta.scope.viewports, say }).then(() => evaluateRun({ run, scenario, config, root })) })
   },
 
+  async design (args) {
+    if (args._[0] !== 'lint') throw new UserError('Usage: kaloko design lint [--env <design env> | --dir design/] [--scenario file] [--all] [--strict] [--json]')
+    const { config, root } = await context(args)
+    let run = null
+    try { run = await resolveRun({ root, output: config.output, run: args.run }) } catch {}
+    let dir = typeof args.dir === 'string' ? resolve(args.dir) : null
+    if (!dir) {
+      const runEnv = run ? environment(config, run.meta.environment.name) : null
+      const env = typeof args.env === 'string' ? environment(config, args.env) : runEnv?.kind === 'design' ? runEnv : Object.keys(config.environments).map((n) => environment(config, n)).find((e) => e.kind === 'design')
+      if (!env) throw new UserError('No design environment: pass --dir <folder> or --env <design env>.')
+      dir = designDir(env, root)
+    }
+    const scenario = typeof args.scenario === 'string' && /\.ya?ml$/.test(args.scenario) ? await loadScenario(resolve(args.scenario)) : run ? await loadScenario(resolve(root, run.meta.scenario_file)).catch(() => null) : null
+    const report = await lintDesign({ dir, scenario })
+    say(args.json ? JSON.stringify(report, null, 2) : formatLint(report, { all: !!args.all, max: args.all ? 500 : 60 }))
+    if (report.errors || (args.strict && report.warnings)) process.exitCode = 1
+  },
+
   async history (args) {
     const { config, root } = await context(args)
     const scenarioId = await scenarioIdOf(args, config, root)
@@ -1234,7 +1273,7 @@ const commands = {
     const d = compareRuns(run, base)
     if (args.json) { say(JSON.stringify(d, null, 2)); return }
     say(formatComparison(d))
-    if (config.share?.url && run.org) say(`\nCanvas: ${config.share.url.replace(/\/$/, '')}/${run.org}/runs/${run.id}/#cmp=${base.id}`)
+    if (config.share?.url && run.org) { const { serviceUrl } = await import('./lib/service.mjs'); say(`\nCanvas: ${serviceUrl(config)}/${run.org}/runs/${run.id}/#cmp=${base.id}`) }
   },
 
   async draft (args) {
@@ -1290,6 +1329,15 @@ const commands = {
   async export (args) {
     const { config, root } = await context(args)
     const client = service(config)
+    if (args.design) {
+      // open formats only: the version as a folder (or zip) that opens from disk without Kaloko
+      const scenarioId = await scenarioIdOf(args, config, root)
+      const v = typeof args.version === 'string' ? args.version : typeof args.design === 'string' ? args.design : null
+      const ref = args.draft ? 'draft' : v ? `v${v.replace(/^v/, '')}` : typeof args.run === 'string' ? args.run : 'design'
+      const out = typeof args.out === 'string' ? resolve(args.out) : resolve(root, config.output, 'design-export', `${scenarioId}-${ref}`)
+      await exportDesign({ config, scenarioId, client, ref, branch: typeof args.branch === 'string' ? args.branch : 'main', out, say })
+      return
+    }
     if (args.live) {
       const scenarioId = await scenarioIdOf(args, config, root)
       let out = typeof args.out === 'string' ? resolve(args.out) : null

package/src/lib/access.mjs

@@ -119,6 +119,13 @@ export async function contextOptions (env, { root, config, account } = {}) {
   return options
 }
 
+/** The gate for requests made outside the browser (link checks): headers for the gate's origins only, Basic, mTLS. */
+export async function gateForRequests (env, { root } = {}) {
+  const headers = gateHeaders(env)
+  const options = await contextOptions(env, { root })
+  return { headers, toGate: Object.keys(headers).length ? originMatcher(gateOrigins(env)) : () => false, httpCredentials: options.httpCredentials || null, clientCertificates: options.clientCertificates || [] }
+}
+
 /** A new browser context with the environment's gate, policy and (optionally) an account's session. */
 export async function newContext (browser, env, opts = {}) {
   const context = await browser.newContext(await contextOptions(env, opts))

package/src/lib/build.mjs

@@ -1,5 +1,6 @@
 import { parsePlan, coverage, flaky } from './coverage.mjs'
 import { readFile, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { readJson, writeJson } from './util.mjs'
 import { readCaptures, runPaths, listRuns } from './run.mjs'
@@ -140,7 +141,9 @@ export async function writePreview ({ run, manifest }) {
     for (const [l, vps] of Object.entries(n.captures)) { captures[l] = {}; for (const [vp, c] of Object.entries(vps)) captures[l][vp] = c?.tree ? { ...c, tree_inline: await readJson(join(run.dir, c.tree), null) } : c }
     return { ...n, captures }
   }
-  const preview = { ...manifest, nodes: await Promise.all(manifest.nodes.map(async (n) => (n.stack ? { ...n, stack: { ...n.stack, items_inline: (await readJson(join(run.dir, n.stack.items), { items: [] })).items } } : withTrees(n)))) }
+  // design runs: live steps open from the merged tree, where links between steps resolve (design.mjs copyLive)
+  const site = existsSync(join(run.dir, 'live', 'site')) ? { live_site: 'live/site/' } : {}
+  const preview = { ...manifest, ...site, nodes: await Promise.all(manifest.nodes.map(async (n) => (n.stack ? { ...n, stack: { ...n.stack, items_inline: (await readJson(join(run.dir, n.stack.items), { items: [] })).items } } : withTrees(n)))) }
   const json = JSON.stringify(preview).replace(/</g, '\\u003c')
   const html = template.replace('/*__QAWALK_RUN__*/null', () => json)
   await writeJson(runPaths(run.dir).manifest, manifest)

package/src/lib/capture.mjs

@@ -55,6 +55,7 @@ import { criteriaHash } from './evaluate.mjs'
 import { consoleEntriesFor } from './console.mjs'
 import { redact, redactDeep } from './secrets.mjs'
 import { readFields } from './stack.mjs'
+import { checkLinks, checkHreflang, requester, walkCache, NETWORK_ASSERTS, isolatedRequest, cacheScope } from './linkcheck.mjs'
 
 /** Probe arguments derived from the node's criteria. */
 export function probeArgs (node, maxChars, design = false) {
@@ -101,6 +102,7 @@ export async function captureStep ({ page, node, locale, viewports, run, console
   const paths = runPaths(run.dir)
   const original = page.viewportSize()
   const results = []
+  let netResults = null
   for (const [viewport, [width, height]] of Object.entries(viewports)) {
     const now = page.viewportSize()
     if (!now || now.width !== width || now.height !== height) await page.setViewportSize({ width, height })
@@ -153,6 +155,12 @@ export async function captureStep ({ page, node, locale, viewports, run, console
     const ownStatus = (e) => result.http_status >= 400 && /^Failed to load resource: the server responded with a status of \d+/.test(e.text) && e.src && sameDocument(e.src, url)
     const errors = consoleEntries.filter((e) => e.type !== 'blocked' && sameDocument(e.url, url) && !e.text.includes('ERR_BLOCKED_BY_CLIENT') && !ownStatus(e)).map((e) => e.text)
     const blocked = consoleEntries.filter((e) => e.type === 'blocked').map((e) => `${e.text}`)
+    // network checks (internal links, hreflang pairs) run once per page, outside the page, with a walk-wide cache
+    const net = (node.criteria || []).filter((c) => c.check.type === 'deterministic' && NETWORK_ASSERTS.has(c.check.assert))
+    if (net.length) {
+      netResults ||= await networkChecks(page, net, url, { run, locale })
+      Object.assign(result.checks, netResults)
+    }
     for (const c of node.criteria || []) {
       if (c.check.type === 'deterministic' && c.check.assert === 'no_console_errors') {
         result.checks[c.id] = collected === null
@@ -214,6 +222,50 @@ export async function captureCrop ({ page, node, locale, selector, title, run, p
   return entry
 }
 
+/**
+ * links_ok and hreflang_pairs for the current page: { [criterion id]: { ok, evidence } }. The requests go through an
+ * isolated request context (linkcheck.mjs), so the walker's cookies, language and session stay as they were.
+ * links_ok follows links only on a readonly environment or scenario, or when the check says `follow: true`.
+ */
+export async function networkChecks (page, criteria, url, { run = null, locale = '', factory = null } = {}) {
+  const out = {}
+  const readonly = !!(run?.meta?.environment?.readonly || run?.meta?.scenario?.readonly)
+  const follows = (c) => c.check.assert !== 'links_ok' || readonly || c.check.follow === true
+  const todo = criteria.filter((c) => {
+    if (follows(c)) return true
+    out[c.id] = { ok: null, evidence: 'links not followed: the environment and scenario are not readonly (set follow: true on the check to opt in)' }
+    return false
+  })
+  if (!todo.length) return out
+  let request
+  let get
+  try {
+    request = await isolatedRequest(page.context(), { factory })
+    const { cookies = [] } = await page.context().storageState().catch(() => ({}))
+    get = requester(request, walkCache, cacheScope({ environment: run?.meta?.environment?.name || '', locale, cookies }))
+  } catch (error) {
+    for (const c of todo) out[c.id] = { ok: null, evidence: `network checks unavailable: ${error.message}` }
+    await request?.dispose().catch(() => {})
+    return out
+  }
+  try {
+    const doc = await page.evaluate((sels) => ({
+      lang: document.documentElement.getAttribute('lang') || '',
+      alternates: [...document.querySelectorAll("link[rel~='alternate'][hreflang][href]")].map((l) => ({ hreflang: l.getAttribute('hreflang').toLowerCase(), href: l.href })),
+      links: Object.fromEntries(sels.map((sel) => [sel, (() => { try { return [...document.querySelectorAll(sel)].map((a) => a.href).filter(Boolean) } catch { return [] } })()]))
+    }), [...new Set(todo.filter((c) => c.check.assert === 'links_ok').map((c) => c.check.selector || 'a[href]'))]).catch(() => null)
+    for (const c of todo) {
+      if (!doc) { out[c.id] = { ok: null, evidence: 'page could not be read for network checks' }; continue }
+      try {
+        out[c.id] = c.check.assert === 'links_ok'
+          ? await checkLinks({ links: doc.links[c.check.selector || 'a[href]'] || [], pageUrl: url, get, max: c.check.max ?? undefined, exclude: c.check.pattern || null })
+          : await checkHreflang({ alternates: doc.alternates, pageUrl: url, lang: doc.lang, get, min: c.check.min ?? 2 })
+      } catch (error) { out[c.id] = { ok: false, evidence: `check error: ${error.message}` } }
+    }
+  } finally { await request.dispose().catch(() => {}) }
+  return out
+}
+
 function sameDocument (a, b) {
   try {
     const x = new URL(a); const y = new URL(b)

package/src/lib/config.mjs

@@ -9,9 +9,13 @@ export const CONFIG_FILE = 'kaloko.config.yml'
 /** The file name before the rename to Kaloko; still found, so existing projects keep working. */
 export const LEGACY_CONFIG_FILE = 'qawalk.config.yml'
 
-/** Environment variables were QAWALK_*; the old names still work and fill the KALOKO_* ones that are not set. */
+/** Environment variables were QAWALK_*: either name fills the other when that one is not set, so new .env files work
+ *  with configs that still name QAWALK_TOKEN (share.token_env) and old .env files work with the new defaults. */
 export function aliasLegacyEnv (vars = process.env) {
-  for (const [k, v] of Object.entries(vars)) if (k.startsWith('QAWALK_') && vars[`KALOKO_${k.slice(7)}`] == null) vars[`KALOKO_${k.slice(7)}`] = v
+  for (const [k, v] of Object.entries(vars)) {
+    const m = k.match(/^(QAWALK|KALOKO)_(.+)$/)
+    if (m && vars[`${m[1] === 'QAWALK' ? 'KALOKO' : 'QAWALK'}_${m[2]}`] == null) vars[`${m[1] === 'QAWALK' ? 'KALOKO' : 'QAWALK'}_${m[2]}`] = v
+  }
 }
 aliasLegacyEnv()
 
@@ -113,5 +117,7 @@ export async function loadEnvFiles (files) {
       if (!m || process.env[m[1]] !== undefined) continue
       process.env[m[1]] = m[2].replace(/^(['"])(.*)\1$/, '$2')
     }
+    // per file, so a project .env with a former name still wins over a user-level file with the new one
+    aliasLegacyEnv()
   }
 }