kaloko 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Your AI agents build; Kaloko walks every screen, puts it on one canvas and records who approved what.",
   "keywords": [
     "qa",

package/schemas/config.v1.json

@@ -124,6 +124,17 @@
         }
       }
     },
+    "traffic": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Traffic data per page (#157), opt-in: Search Console clicks, impressions, CTR and position and GA4 sessions and conversions, joined by URL onto stack pages (items.json traffic) and the rows of kaloko export findings (impact, sorted by it); with the seo pack a stack also gets HC127 (high impressions, low CTR). Nothing is requested unless gsc or ga4 is set. A scenario's traffic block replaces the config's.",
+      "properties": {
+        "file": { "oneOf": [{ "type": "string" }, { "type": "array", "minItems": 1, "items": { "type": "string" } }], "description": "CSV exports of Search Console (Pages) or GA4 (landing pages), English or Czech headers; a path relative to the file that names it." },
+        "gsc": { "type": "object", "additionalProperties": false, "required": ["property"], "properties": { "property": { "type": "string", "minLength": 1, "description": "The Search Console property: sc-domain:example.com or https://www.example.com/." }, "credentials_env": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "Variable with the path of the service account JSON key (or the JSON itself). Default GOOGLE_APPLICATION_CREDENTIALS." }, "days": { "type": "integer", "minimum": 1, "maximum": 480, "description": "Days of data, default 28 (ending two days ago; Search Console data comes in late)." } }, "description": "Search Console API (searchanalytics.query by page) with a service account added to the property as a user. Requested once per run and cached in the run folder .cache." },
+        "ga4": { "type": "object", "additionalProperties": false, "required": ["property"], "properties": { "property": { "type": "string", "minLength": 1, "pattern": "^(properties/)?[0-9]+$", "description": "The GA4 property id (123456789 or properties/123456789)." }, "credentials_env": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "Variable with the path of the service account JSON key (or the JSON itself). Default GOOGLE_APPLICATION_CREDENTIALS." }, "days": { "type": "integer", "minimum": 1, "maximum": 480, "description": "Days of data, default 28 (ending yesterday)." } }, "description": "GA4 Data API (runReport: sessions and key events by landing page) with a service account added to the property as a viewer. Requested once per run and cached in the run folder .cache." },
+        "low_ctr": { "type": "object", "additionalProperties": false, "description": "HC127 thresholds: a page with at least min_impressions impressions fails when its CTR is below ratio x the site's median CTR at similar positions (1-3, 4-10, 11-20).", "properties": { "min_impressions": { "type": "integer", "minimum": 1, "default": 100 }, "ratio": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "default": 0.5 } } }
+      }
+    },
     "walk": {
       "type": "object",
       "additionalProperties": false,

package/schemas/run.v1.json

@@ -700,7 +700,7 @@
               "evidence": { "type": ["string", "null"] },
               "check": { "type": "object" },
               "help": { "type": "object" },
-              "cross_page": { "type": "boolean", "description": "Stack steps (#151): a check across the stack's pages (HC121–HC126: duplicates, canonicals, hreflang pairs, sitemap pages). counts says how many pages are affected; it cannot be adopted as a criterion." },
+              "cross_page": { "type": "boolean", "description": "Stack steps (#151): a check across the stack's pages (HC121–HC126: duplicates, canonicals, hreflang pairs, sitemap pages; HC1005: pages without their own version in a walked locale, with items.variants). counts says how many pages are affected; it cannot be adopted as a criterion." },
               "urls": { "type": "array", "items": { "type": "string" }, "description": "Cross-page checks: the first affected addresses (at most 20); the stack's items.json has every group." }
             }
           }
@@ -766,9 +766,19 @@
               "description": "Rotating sample (items.rotate), per locale: mode (week or run), week or run, offset, limit, total, rounds (runs to cover every page), covered, never (pages not checked yet) and oldest_checked.",
               "additionalProperties": { "type": "object" }
             },
+            "variants": {
+              "type": "object",
+              "description": "Locale variants (items.variants: hreflang): mode, source_locale, and per other locale the number of source pages without their own version there (missing) and of versions several source pages share (shared). items.json lists them under variants.locales.",
+              "properties": {
+                "mode": { "type": "string" },
+                "source_locale": { "type": ["string", "null"] },
+                "missing": { "type": "object", "additionalProperties": { "type": "integer" } },
+                "shared": { "type": "object", "additionalProperties": { "type": "integer" } }
+              }
+            },
             "cross_page": {
               "type": "array",
-              "description": "Cross-page checks of a stack with the seo pack (#151): id, verdict, pages compared and pages affected. items.json has them in full under cross_page (groups with the affected addresses) and marks each affected page with cross_fails.",
+              "description": "Cross-page checks of a stack with the seo pack (#151), and HC1005 with locale variants: id, verdict, pages compared and pages affected. items.json has them in full under cross_page (groups with the affected addresses) and marks each affected page with cross_fails.",
               "items": { "type": "object" }
             }
           }

package/schemas/scenario.v1.json

@@ -113,6 +113,17 @@
         }
       }
     },
+    "traffic": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Traffic data per page (#157), opt-in: Search Console clicks, impressions, CTR and position and GA4 sessions and conversions, joined by URL onto stack pages (items.json traffic) and the rows of kaloko export findings (impact, sorted by it); with the seo pack a stack also gets HC127 (high impressions, low CTR). Nothing is requested unless gsc or ga4 is set. A scenario's traffic block replaces the config's.",
+      "properties": {
+        "file": { "oneOf": [{ "type": "string" }, { "type": "array", "minItems": 1, "items": { "type": "string" } }], "description": "CSV exports of Search Console (Pages) or GA4 (landing pages), English or Czech headers; a path relative to the file that names it." },
+        "gsc": { "type": "object", "additionalProperties": false, "required": ["property"], "properties": { "property": { "type": "string", "minLength": 1, "description": "The Search Console property: sc-domain:example.com or https://www.example.com/." }, "credentials_env": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "Variable with the path of the service account JSON key (or the JSON itself). Default GOOGLE_APPLICATION_CREDENTIALS." }, "days": { "type": "integer", "minimum": 1, "maximum": 480, "description": "Days of data, default 28 (ending two days ago; Search Console data comes in late)." } }, "description": "Search Console API (searchanalytics.query by page) with a service account added to the property as a user. Requested once per run and cached in the run folder .cache." },
+        "ga4": { "type": "object", "additionalProperties": false, "required": ["property"], "properties": { "property": { "type": "string", "minLength": 1, "pattern": "^(properties/)?[0-9]+$", "description": "The GA4 property id (123456789 or properties/123456789)." }, "credentials_env": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "Variable with the path of the service account JSON key (or the JSON itself). Default GOOGLE_APPLICATION_CREDENTIALS." }, "days": { "type": "integer", "minimum": 1, "maximum": 480, "description": "Days of data, default 28 (ending yesterday)." } }, "description": "GA4 Data API (runReport: sessions and key events by landing page) with a service account added to the property as a viewer. Requested once per run and cached in the run folder .cache." },
+        "low_ctr": { "type": "object", "additionalProperties": false, "description": "HC127 thresholds: a page with at least min_impressions impressions fails when its CTR is below ratio x the site's median CTR at similar positions (1-3, 4-10, 11-20).", "properties": { "min_impressions": { "type": "integer", "minimum": 1, "default": 100 }, "ratio": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "default": 0.5 } } }
+      }
+    },
     "tags": {
       "type": "array",
       "items": {
@@ -491,6 +502,14 @@
               "maximum": 10000,
               "description": "At most this many pages (default 500)"
             },
+            "variants": {
+              "enum": ["hreflang"],
+              "description": "Locale variants of one page: the list, limit and rotation come from items.source_locale, and every other locale walks each page's own hreflang alternate for that locale (from the page's HTML head, its Link header or the sitemap's xhtml:link). The item id comes from the source page, so a page and its translations are one item; a page without a version in a locale is reported (HC1005) instead of dropped silently. x-default never stands for a locale."
+            },
+            "source_locale": {
+              "type": "string",
+              "description": "With variants: the locale whose list is walked (default: the scenario's first locale). One of the scenario's locales."
+            },
             "rotate": {
               "enum": ["week", "run"],
               "description": "Rotating sample: each run takes limit pages starting at a stable offset, the ISO week (week) or the number of runs so far in this output folder (run), so the whole list is covered over several runs."

package/skills/kaloko/reference/integrations.md

@@ -72,6 +72,22 @@ kaloko schedule hook <id>       # URL + secret that start the run after a deploy
   script that only calls `page.goto`). Steps that click or type are left out and
   named in the answer. Criteria decided: `exists`, `absent`, `count`, `text_*`,
   `attr_*`, `title_matches`, `meta_matches`; the rest shows "not evaluated".
+- Stack steps: pages from `items.urls`, `items.sitemap` or `items.robots`
+  (gzip and indexes too) with `match`/`exclude` (string or per locale), `limit`
+  and `rotate: week`, picked like `kaloko walk` picks them. Read without
+  screenshots (one `/scrape` per page in the step's first viewport): the
+  criteria above, index fields (title, h1, description, words, jsonld_types,
+  meta and selector fields; `http` stays empty) and `items.json` on the canvas.
+  Read over several 15-minute ticks (150 pages each), at most 1,000 stack pages
+  per run and 5 × limit sitemap addresses per locale; each page counts against
+  the monthly budget, and a spent budget waits up to a day, then shares with a
+  note. Run now, hooks and edits queue behind a run under way. Patterns: ≤ 300
+  characters, no backreferences or lookaround. `crawl`, `script` and `file` sources, item scripts and
+  `items.resolve` edit links need the full walk.
+- Base URL per locale: an environment with `base_url: { default: …, cs: … }`
+  is scheduled as it is; each locale opens its own address, else `default`.
+  `kaloko schedule list` shows stack progress and the last run's new and fixed
+  health results.
 - Health alerts: a hosted run (and a run shared from CI) compares its health
   with the previous run of the scenario and alerts the followers, the channels
   and the `health.worse` webhook on a new error-level finding. Each schedule
@@ -83,8 +99,15 @@ kaloko schedule hook <id>       # URL + secret that start the run after a deploy
   run per page (`…/health/diff`: new, fixed, still open, first seen). A
   `read:health` token reads these and nothing else; the `health.changed`
   webhook says when something is new or fixed. help/reference/health-api.md.
+- Findings: `GET …/scenarios/<id>/findings` (MCP `list_findings`) groups a
+  scenario's open results by check, site, locale and step, with a status
+  people set (acknowledged, ignored with a reason) and fixed when no page
+  fails. A scenario may open one Jira / Linear issue per new finding
+  (`PUT …/findings/sync { tracker, min_severity }`, Developer / Tester): at
+  most 20 per run, a comment on big changes, closed when fixed. Switching it
+  on or ignoring findings is the team's call, not an agent's.
 - Does not work for: native apps, local or private addresses (localhost, IPs,
-  `.local`), header credentials, base URLs per locale.
+  `.local`), header credentials, stacks listed by crawl, script or file.
 - For those, or for the full walk on a schedule, write a GitHub Actions
   workflow instead: `kaloko schedule export github --scenario <file> --env <name>
   [--every week] [--at 5]`. It names the repository secrets it needs.

package/skills/kaloko/reference/mcp.md

@@ -54,6 +54,7 @@ is null. Projects and products come complete, without pages.
 | `get_health` | the advisory health of a run (`run_id`), the newest run of a scenario (`scenario`) or the trend of a project (`project`): findings by severity, pack and step with evidence and a fix, and what is new or fixed since the previous run; never a verdict, see [evaluation.md#health](evaluation.md#health) |
 | `get_health_aggregate` | health counted for a dashboard (`run_id`, or `scenario` and `environment` for its newest run; `by` locale, step, check, pack; filters; `top` pages per group): pass / fail / unsure / not evaluated per group, the most affected pages, and new / fixed / still open since the previous run; group ids are stable across runs |
 | `get_health_diff` | per page, locale and check what is new, fixed or still open since the previous run (`state` picks one list), each with `first_seen` (run and date); ids `step\|locale\|check\|page` are stable across runs |
+| `list_findings` | a scenario's open results grouped into findings (`scenario`, `environment`; filters `locale`, `step`, `check`, `status`): fingerprint `check\|site\|locale\|step`, severity, pages affected, up to 10 sample pages with `edit_url`, first / last seen, status (open, acknowledged, ignored with a reason, fixed) and the tracker issue. Read-only: fix the worst first; acknowledging or ignoring is the team's call |
 | `adopt_health_check` | turns a health check into an acceptance criterion of the scenario (`run_id`, `step`, `check` such as `HC103`, `text` to reword it; it becomes `AC103` with `from: HC103`); Developer / Tester role. Only when the person asks; `kaloko health pull` then writes it into the scenario file |
 | `get_affected_steps` | which steps of a scenario changed files reach, with the reason per step (`scenario`, `changed_files`, `run_id`, `upstream`); route files are matched against the step paths and URLs of the newest run. Imports and `affects:` globs need the repository: `kaloko affected` follows them |
 

package/skills/kaloko/reference/stacks.md

@@ -24,7 +24,10 @@ the languages and the biggest content families and writes
 language, packs seo and aeo). Read the comment at the top of the file:
 families it paired across languages by size are guesses to check. Then
 `kaloko validate`, `kaloko walk --limit 20`, and
-`kaloko schedule export github`. See help/how-to/seo-monitor.md.
+`kaloko schedule export github`. See help/how-to/seo-monitor.md. On
+Business, `kaloko schedule add` runs urls, sitemap and robots stacks on
+Kaloko's side without screenshots (DOM checks and index fields only; see
+reference/integrations.md → Hosted runs).
 
 Not for a flow of different screens: those stay separate steps. A stack
 step does not click through anything. It opens each page by URL. Use a
@@ -45,6 +48,7 @@ step script only to prepare each page, for example to dismiss a dialog
                                             # or a map by locale: { default: '^/blog/', fi: '^/fi/blogi/' }
     limit: 800                              # default 500, at most 10000
     # rotate: week                          # each ISO week the next `limit` pages (run: each run)
+    # variants: hreflang                    # translations as variants of one page (see below)
     semantic_sample: 20                     # semantic criteria on 20 pages only
     # semantic_order: priority              # failing and least recently checked pages first
     # viewports: [desktop]                  # default: the first viewport of the scenario
@@ -155,10 +159,80 @@ HC1101–HC1107, `site.json` in the run, `site` in the manifest). Off the
 `production` environment HC1102 is a warning and HC1103 is skipped;
 `health.site.environments: [production]` runs them there only.
 
+Traffic data (#157) is opt-in: `traffic:` in kaloko.config.yml or the
+scenario, with `file` (a Search Console or GA4 CSV export, English or Czech
+headers), `gsc: { property }` and `ga4: { property }` (APIs through a service
+account key named by `credentials_env`, default
+GOOGLE_APPLICATION_CREDENTIALS; nothing is requested without them; answers
+cached per run in <output>/.cache/traffic). Each page in `items.json` then has
+`traffic: { clicks, impressions, ctr, position, sessions, conversions }`, the
+node `stack.traffic` counts the pages with data, `kaloko export findings`
+adds the numbers and `impact` (weight 3 for errors and failed acceptance, 1
+for warnings, × impressions + 10 × (clicks + sessions) + 100 × conversions)
+and sorts by it, and the `seo` pack adds HC127 (CTR below half the site's
+median at similar positions, pages with 100+ impressions). Sort a fix list
+by impact before handing it over; never put the key in the scenario.
+
 A step `execution.script` still works. It is called with `item` in the
 context, opens `item.url` itself and may call `capture()`. Without a script,
 the walk opens each page and captures it.
 
+## One page in every language (`variants: hreflang`)
+
+One item is one page; its locales are variants of it. Without more setup,
+each locale reads its own list, so a Czech product and its Slovak
+translation become two items with different ids, the locales sample
+different pages and a missing translation is invisible. For a multilingual
+stack, set:
+
+```yaml
+  items:
+    robots: true
+    match: '^/eshop/'
+    variants: hreflang
+    source_locale: cs                       # default: the scenario's first locale
+    limit: 100
+    rotate: week
+```
+
+- The list, `match`/`exclude`, `limit` and `rotate` are taken in
+  `source_locale` (its base URL, `{locale}` = the source locale) for every
+  locale, so all locales walk the same window. Item ids come from the
+  source pages; `--items` takes an id or a source path.
+- In another locale each chosen page's alternate for that locale is walked:
+  `<link rel="alternate" hreflang>` in the raw HTML head (no JavaScript),
+  else the `Link` header, else the sitemap's `xhtml:link`. Matching: the
+  same tag (`en-us` for `en_US`), else the bare language for a locale with a
+  region, else the first regional tag for a bare locale (`sk-sk` for `sk`).
+  `x-default` never stands for a locale. The page is read with the
+  environment's gate (headers, HTTP Basic, client certificates) and the
+  walk's cookies, on the environment's own origins only; 15 s and 1 MB at
+  most, stopping at `</head>`; a timeout or 5xx is tried once more. When no
+  alternate is on the host the page was read from (staging naming
+  production, also one domain per language), every alternate opens with its
+  path on the walked locale's origin.
+- A page with no alternate for the locale, only `x-default`, an alternate
+  that points back to the page itself (another language), or a page that
+  cannot be read is not walked in that locale and is reported: the walk
+  says how many, `steps/<step>/variants.<locale>.json` keeps the list,
+  `items.json` marks the item (`missing: [sk]`) and lists every page under
+  `variants.locales`, the node gets `stack.variants`, HC1005 counts them
+  (advisory, also without the `seo` pack), and `kaloko export findings`
+  gives one row per page and locale at the source URL. Several source pages
+  leading to one alternate (a fallback to a listing or home) also count in
+  HC1005; they are walked. A translation that answers 4xx/5xx is walked
+  and also counts as missing (`error 404`). Reciprocity is HC125 (`seo` pack).
+- The source page is read once per walk, whichever locale needs it. Each
+  capture of a variant keeps its own `path` in `items.json`; the item's
+  `path` and id are the source page's, and its `url`, title and fields too
+  when the run walks the source locale (else those of the first walked
+  locale).
+- A script that lists pages per locale instead: give each page the same
+  `key` in every locale (for example the source path), so they are one item.
+- Hosted runs (`kaloko schedule add`) do not group variants yet: there each
+  locale reads its own list and HC1005 is not reported (`kaloko validate`
+  warns). Use `kaloko walk` or the scheduled GitHub workflow.
+
 ## Cost and size: choose deliberately
 
 - Deterministic criteria and packs run on every page. They are cheap.
@@ -213,8 +287,9 @@ the walk opens each page and captures it.
 
 Say how many pages were walked, how many fail and on which criteria (with
 two or three example paths), whether the limit cut the list, and that
-semantic criteria covered only the sample. Put the full list in the CSV or
-the MCP result rather than in the issue.
+semantic criteria covered only the sample. With `variants: hreflang`, also
+say per locale how many source pages have no version there (HC1005). Put the
+full list in the CSV or the MCP result rather than in the issue.
 
 ## Design environments
 

package/src/cli.mjs

@@ -18,7 +18,7 @@ import { newContext, accountFor, gateHeaders, gateOrigins, originMatcher, gateFo
 import { configureGate, disposeShared } from './lib/linkcheck.mjs'
 import { rememberEnvironment } from './lib/secrets.mjs'
 import { evaluateRun, semanticPrefetch } from './lib/evaluate.mjs'
-import { buildManifest, writePreview, attentionLines } from './lib/build.mjs'
+import { buildManifest, writePreview, attentionLines, runTraffic } from './lib/build.mjs'
 import { stabilityCmd, pullDrawn } from './lib/stability.mjs'
 import { signoffCmd, evidenceCmd } from './lib/signoff.mjs'
 import { localized, readJson, writeJson, UserError, UsageError, globToRegExp, failureStreak, expiryNote, SUPPORT_LINE, SUPPORT_EMAIL, NO_ORG, EXIT, parseDuration } from './lib/util.mjs'
@@ -33,7 +33,7 @@ import { detectProject, initScenario, skeletonScenario, scenarioHeader, formatDe
 import { checkSlug, checkName, setConfigKeys, createProject, renameProject, syncProject, shareProjectNote } from './lib/projects-cli.mjs'
 import { recheckCaptures } from './lib/recheck.mjs'
 import { runFindings, findingsText } from './lib/findings.mjs'
-import { resolveItems, fieldsOf, DEFAULT_LIMIT, timeLeft, rotationState, rotationCoverage } from './lib/stack.mjs'
+import { resolveItems, fieldsOf, DEFAULT_LIMIT, timeLeft, rotationState, rotationCoverage, sourceLocaleOf, variantReader } from './lib/stack.mjs'
 import { walkSiteChecks, siteChecksOn } from './lib/site.mjs'
 import { DEFAULTS as JEV_DEFAULTS } from './lib/jev.mjs'
 import { expandPacks } from './lib/packs.mjs'
@@ -319,7 +319,9 @@ Results
   export findings [<run>] [--format csv|json] [--locale l] [--step id] [--out file]
                                     The fix list of a local run: every failing criterion and health check per page and
                                     locale with its evidence, the page's edit_url and content_ref (from the item script
-                                    or items.resolve) and the walk that checks it again (kaloko walk --steps s --items p)
+                                    or items.resolve) and the walk that checks it again (kaloko walk --steps s --items p);
+                                    with traffic: in the config, also clicks, impressions, sessions and an impact
+                                    score, sorted by it
   public [--run id] [--off]         Make a shared run readable without sign-in (admin; testers may refresh an already public scenario)
   stability [--last 4 | --runs a,b] [--same-commit] [--apply] [--json]
                                     Regions that change on every run or move while the page is idle (clocks, ads,
@@ -807,11 +809,31 @@ async function exportScenario ({ args, config, root, client }) {
  * Walks a stack step: resolves its pages, then opens and captures each one with the step's criteria and index
  * fields (HTTP status of the main document included). A step script, when given, runs per page with `item`.
  */
-async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir, config, consoleFile, args, keys = null, tag = '' }) {
+async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir, config, consoleFile, args, keys = null, tag = '', cache = null, gate = null }) {
   // a rotating sample (items.rotate) remembers between runs how many runs walked it and when each page was checked
-  const state = node.items?.rotate ? await rotationState(join(run.dir, '..', '.cache', 'stack', scenario.id, `${node.id}.${locale}.json`), run.meta.id) : null
-  const { items, total, truncated, all, rotation, resolve_failed: unresolved, resolve_error: unresolvedWhy } = await resolveItems({ node, base: baseUrl(env, locale), page, scenarioDir, env, locale, scenario, limit: Number(args.limit) || undefined, rotation: { run: state?.run || 0 }, checked: state?.checked || null, only: list(args.items) })
+  const statePath = (l) => join(run.dir, '..', '.cache', 'stack', scenario.id, `${node.id}.${l}.json`)
+  const state = node.items?.rotate ? await rotationState(statePath(locale), run.meta.id) : null
+  // locale variants (#176): every locale walks the window of the source list, so a rotation by runs counts the runs of
+  // the step once for all locales (whichever of them a run walks), not per locale
+  const sourceLocale = node.items?.variants ? sourceLocaleOf(node, scenario, locale) : locale
+  const counter = state && node.items.variants && node.items.rotate === 'run' ? await rotationState(statePath('variants'), run.meta.id) : null
+  const round = counter ? counter.run : state?.run || 0
+  // locale variants read the source pages for their hreflang with the environment's access (variantReader)
+  const reader = node.items?.variants ? await variantReader({ page, gate, origins: envOrigins(env, scenario, locale) }) : null
+  let resolved
+  try { resolved = await resolveItems({ node, base: baseUrl(env, locale), sourceBase: baseUrl(env, sourceLocale), page, scenarioDir, env, locale, scenario, limit: Number(args.limit) || undefined, rotation: { run: round }, checked: state?.checked || null, only: list(args.items), cache, readPage: reader?.read || null }) } finally { await reader?.dispose() }
+  const { items, total, truncated, all, rotation, partial, variants, resolve_failed: unresolved, resolve_error: unresolvedWhy } = resolved
   if (unresolved) say(`! ${node.id} ${locale}${tag}: items.resolve failed for ${unresolved} page(s), walked without an edit link (${unresolvedWhy})`)
+  if (variants) {
+    // the build marks the pages without a version in this locale; a partial walk (--items) updates its pages only
+    const file = join(run.dir, 'steps', node.id, `variants.${locale}.json`)
+    const before = partial ? await readJson(file, null) : null
+    const asked = new Set([...items.map((it) => it.id), ...variants.missing.map((m) => m.id)])
+    const keep = (list) => (before?.[list] || []).filter((m) => !asked.has(m.id) && !(m.ids || []).some((id) => asked.has(id)))
+    await writeJson(file, before ? { ...variants, pages: before.pages, missing: [...keep('missing'), ...variants.missing], shared: [...keep('shared'), ...variants.shared] } : variants)
+    if (variants.missing.length) say(`! ${node.id} ${locale}${tag}: ${variants.missing.length} of ${variants.pages} ${variants.source_locale} page(s) have no ${locale} version (hreflang), e.g. ${variants.missing[0].path}: ${variants.missing[0].reason}`)
+    if (variants.shared.length) say(`! ${node.id} ${locale}${tag}: ${variants.shared.length} ${locale} page(s) stand for several ${variants.source_locale} pages, e.g. ${variants.shared[0].url}`)
+  }
   // --items picked the pages from the whole list (resolveItems only); a partial walk leaves the rotation state alone
   const chosen = items
   const passKeys = keys || engineKeys(run.meta.scope, 'chromium')
@@ -820,7 +842,7 @@ async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir,
   const passBases = baseViewports({ ...run.meta.scope, viewports: Object.fromEntries(passKeys.map((k) => [k, run.meta.scope.viewports[k]])) })
   const viewports = scopeKeys(run.meta.scope, passKeys, vpNames.length ? vpNames : [passBases[0] || bases[0]])
   if (!Object.keys(viewports).length) { say(`▦ ${node.id} ${locale}${tag}: no viewport of this step in this pass`); return [] }
-  if (rotation) say(`▦ ${node.id} ${locale}${tag}: rotating sample, ${rotation.week ? `week ${rotation.week}` : `run ${rotation.run}`} — pages ${rotation.offset + 1}…${((rotation.offset + items.length - 1) % Math.max(1, total)) + 1} of ${total}, all covered in ${rotation.rounds} ${rotation.week ? 'weeks' : 'runs'}`)
+  if (rotation) say(`▦ ${node.id} ${locale}${tag}: rotating sample, ${rotation.week ? `week ${rotation.week}` : `run ${rotation.run}`} — pages ${rotation.offset + 1}…${((rotation.offset + (variants?.pages ?? items.length) - 1) % Math.max(1, total)) + 1} of ${total}, all covered in ${rotation.rounds} ${rotation.week ? 'weeks' : 'runs'}`)
   say(`▦ ${node.id} ${locale}${tag}: ${chosen.length} page(s)${rotation ? '' : truncated ? ` — limit ${Number(args.limit) || node.items.limit || DEFAULT_LIMIT} reached (${total}+ found; raise items.limit or pass --limit)` : ''}`)
   const fields = fieldsOf(node)
   const script = node.execution?.script ? await import(pathToFileURL(resolve(scenarioDir, node.execution.script)).href) : null
@@ -841,7 +863,7 @@ async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir,
         if (script) await script.default({ page, item, url: () => item.url, locale, env, run: run.meta, capture, acceptDialogs: () => acceptDialogs(page) })
         else await page.goto(item.url, { waitUntil: 'domcontentloaded', timeout: 30000 })
         if (!captured) await capture()
-        ok++; streak.ok('stack'); checkedNow.push(item.path)
+        ok++; streak.ok('stack'); checkedNow.push(item.source_path || item.path)
       } catch (error) {
         failed.push(`${item.id} (${item.path}): ${error.message.split('\n')[0]}`)
         if (streak.record('stack', error.message)) say(`  stopping ${node.id} (${locale}${tag}): the last 5 pages failed with the same error`)
@@ -853,12 +875,16 @@ async function walkStack ({ node, locale, page, env, run, scenario, scenarioDir,
   // the rotation of this locale goes into the run (the stack index shows it) and the pages checked into the state
   if (state && rotation) {
     const checked = await state.save(checkedNow, all)
+    if (counter) await counter.save([], [])
     await writeJson(join(run.dir, 'steps', node.id, `rotation.${locale}.json`), { ...rotation, ...rotationCoverage(all, checked) })
   }
   say(`${failed.length ? '✗' : '✓'} ${node.id} ${locale}${tag}: ${ok}/${chosen.length} page(s) captured`)
   return failed
 }
 
+/** The origins of the environment for the scenario's locales: where the gate and the walk's cookies may go. */
+const envOrigins = (env, scenario, locale) => [...new Set([...(scenario.locales || []), locale].map((l) => { try { return new URL(baseUrl(env, l)).origin } catch { return null } }).filter(Boolean))]
+
 /** Deep link of an app step: a URL scheme as written, a path under the environment's base URL (universal links). */
 function linkFor (env, node, locale) {
   const raw = typeof node.path === 'string' ? node.path : (node.path?.[locale] ?? node.path?.default)
@@ -1107,16 +1133,17 @@ async function exportFindings (args) {
   const { config, root, run, scenario } = await runContext(args)
   // read-only: the manifest and the stack indexes are assembled in memory from the captures, nothing is written
   const indexes = new Map()
-  const manifest = await buildManifest({ run, scenario, config, root, catalog: [], indexes })
+  const traffic = await runTraffic({ run, scenario, config, root })
+  const manifest = await buildManifest({ run, scenario, config, root, catalog: [], indexes, traffic })
   const step = typeof args.step === 'string' ? args.step : null
   if (step && !(manifest.nodes || []).some((n) => n.id === step)) throw new UsageError(`No step ${step} in this run. Steps: ${(manifest.nodes || []).filter((n) => n.kind !== 'decision').map((n) => n.id).join(', ')}.`)
-  const rows = await runFindings(manifest, { stackIndex: (n) => indexes.get(n.id) || null, locale: typeof args.locale === 'string' ? args.locale : null, step })
+  const rows = await runFindings(manifest, { stackIndex: (n) => indexes.get(n.id) || null, locale: typeof args.locale === 'string' ? args.locale : null, step, traffic })
   const format = typeof args.format === 'string' ? args.format : args.json ? 'json' : 'csv'
   const text = findingsText(rows, format, { run: manifest.id, scenario: manifest.scenario?.id || null })
   if (typeof args.out === 'string') {
     await writeFile(resolve(args.out), text)
     const pages = new Set(rows.map((r) => `${r.step}|${r.page || ''}|${r.locale}`)).size
-    say(args.json ? JSON.stringify({ file: resolve(args.out), count: rows.length, pages }) : `${rows.length} finding(s) on ${pages} page(s) → ${relative(process.cwd(), resolve(args.out)) || args.out}${rows.some((r) => r.edit_url) ? ' (with edit links)' : ''}`)
+    say(args.json ? JSON.stringify({ file: resolve(args.out), count: rows.length, pages }) : `${rows.length} finding(s) on ${pages} page(s) → ${relative(process.cwd(), resolve(args.out)) || args.out}${rows.some((r) => r.edit_url) ? ' (with edit links)' : ''}${rows.some((r) => r.impact) ? ', sorted by impact (search and GA4 traffic of the page)' : ''}`)
   } else process.stdout.write(format === 'json' ? `${text}\n` : text)
   return { count: rows.length }
 }
@@ -1581,6 +1608,9 @@ const commands = {
       return
     }
     const pick = list(args.steps)
+    // stacks with locale variants read their source list and each page's hreflang once per walk, for every locale
+    const stackCache = new Map()
+    const stackGate = await gateForRequests(env, { root }) // the gate for requests outside the browser: link checks, hreflang of stack pages
     const locales = list(args.locales) || run.meta.scope.locales
     const scope = run.meta.scope
     // browser engines and device profiles (batch E): one pass each, capturing only its own keys; a run without
@@ -1590,7 +1620,7 @@ const commands = {
     if (!passes.length) throw new UserError(`This run has no captures in ${only.join(', ')} (its browsers: ${enginesOf(scope).join(', ')}).`)
     const needChromium = passes.some((p) => p.engine === 'chromium')
     // --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 }))
+    configureGate(stackGate)
     const conn = args.ephemeral || !needChromium ? 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 || !needChromium ? null : await launchEphemeral(config)
@@ -1686,7 +1716,7 @@ const commands = {
               const consoleFile = shared && !sess ? consoleLog(root, config.output, env.name) : null
               if (node.kind === 'stack') {
                 try {
-                  const bad = await walkStack({ node, locale, page: sPage, env, run, scenario, scenarioDir, config, consoleFile, args, keys: pass.keys, tag })
+                  const bad = await walkStack({ node, locale, page: sPage, env, run, scenario, scenarioDir, config, consoleFile, args, keys: pass.keys, tag, cache: stackCache, gate: stackGate })
                   for (const b of bad) failed.push(`${node.id} (${locale}${tag}) ${b}`)
                 } catch (error) {
                   failed.push(`${node.id} (${locale}${tag}): ${error.message.split('\n')[0]}`)

package/src/lib/build.mjs

@@ -9,15 +9,18 @@ import { layout } from './scenario.mjs'
 import { assembleNode, assembleStack, summarize, runPii } from './manifest-core.mjs'
 import { packageRoot } from './schema.mjs'
 import { variantOf } from './dimensions.mjs'
+import { loadTraffic } from './traffic.mjs'
 
 export { targetOf, statusOf } from './manifest-core.mjs'
 
 /**
  * The run manifest from the captures. `indexes` (a Map) makes it read-only: stack indexes go into the map by step id
- * instead of steps/<step>/items.json and step specs are not written (kaloko export findings).
+ * instead of steps/<step>/items.json and step specs are not written (kaloko export findings). `traffic` is the run's
+ * traffic data (traffic.mjs loadTraffic); left out, it is loaded when the config or the scenario has a traffic block.
  */
-export async function buildManifest ({ run, scenario, config, root, catalog = [], indexes = null }) {
+export async function buildManifest ({ run, scenario, config, root, catalog = [], indexes = null, traffic }) {
   const meta = run.meta
+  if (traffic === undefined) traffic = await runTraffic({ run, scenario, config, root })
   const entries = await readCaptures(run.dir)
   const captures = latestCaptures(entries)
   const attachments = entries.filter((e) => e.type === 'attachment')
@@ -29,7 +32,7 @@ export async function buildManifest ({ run, scenario, config, root, catalog = []
   const mailKeys = viewportNames.filter((k) => variantOf(meta.scope, k).browser === 'chromium')
   const nodes = []
   for (const node of scenario.nodes) {
-    if (node.kind === 'stack') { const p = pos.get(node.id); nodes.push(await buildStack({ run, node, base: { id: node.id, kind: node.kind, title: node.title, path: node.path ?? null, purpose: node.purpose ?? '', col: p.col, lane: p.lane, ...(node.refs?.length ? { refs: node.refs } : {}) }, captures, attachments, indexes })); continue }
+    if (node.kind === 'stack') { const p = pos.get(node.id); nodes.push(await buildStack({ run, node, base: { id: node.id, kind: node.kind, title: node.title, path: node.path ?? null, purpose: node.purpose ?? '', col: p.col, lane: p.lane, ...(node.refs?.length ? { refs: node.refs } : {}) }, captures, attachments, indexes, traffic })); continue }
     const caps = []
     // pages of a stack live in its items index; normal steps take their own captures only
     for (const c of captures.filter((x) => x.node === node.id && !x.item)) {
@@ -102,6 +105,19 @@ export async function buildManifest ({ run, scenario, config, root, catalog = []
   }
 }
 
+/**
+ * The traffic data of a run (#157) when the config or the scenario asks for it; a source that cannot be read is said
+ * on stderr (tokens redacted) and left out, so the run still builds.
+ */
+export async function runTraffic ({ run, scenario, config, root }) {
+  // a scenario's traffic.file is relative to the scenario file; a run without one (older runs) uses the project root
+  const scenarioDir = run.meta.scenario_file ? resolve(root, run.meta.scenario_file, '..') : root
+  const started = run.meta.started_at ? new Date(run.meta.started_at) : new Date()
+  const traffic = await loadTraffic({ config, scenario, root, scenarioDir, runId: run.meta.id, now: Number.isNaN(started.getTime()) ? new Date() : started })
+  for (const p of traffic?.problems || []) process.stderr.write(`! ${p}\n`)
+  return traffic
+}
+
 /** The tools of a run: kaloko and its version, Node.js, the OS, and every browser version a capture reports. */
 export function toolsOf (meta, nodes) {
   const browsers = new Set()
@@ -165,7 +181,7 @@ async function runMedia ({ run, entries }) {
  * A stack step: its pages go to steps/<node>/items.json (qawalk.stack.v1: fields, criteria, and per page the path,
  * status, index fields, capture files and compact results); the node keeps counts, a visual sample and the path.
  */
-async function buildStack ({ run, node, base, captures, attachments, indexes = null }) {
+async function buildStack ({ run, node, base, captures, attachments, indexes = null, traffic = null }) {
   const paths = runPaths(run.dir)
   const list = []
   for (const c of captures.filter((x) => x.node === node.id && x.item)) {
@@ -178,7 +194,10 @@ async function buildStack ({ run, node, base, captures, attachments, indexes = n
   // rotating samples: steps/<node>/rotation.<locale>.json, written by the walk
   const rotation = {}
   for (const l of run.meta?.scope?.locales || []) { const r = await readJson(join(run.dir, 'steps', node.id, `rotation.${l}.json`), null); if (r) rotation[l] = r }
-  const { node: out, index, file } = assembleStack({ node, base, environment: run.meta?.environment?.name || null, captures: list, attachments, rotation })
+  // locale variants (items.variants: hreflang): steps/<node>/variants.<locale>.json, the pages without a version there
+  const variants = {}
+  if (node.items?.variants) for (const l of run.meta?.scope?.locales || []) { const v = await readJson(join(run.dir, 'steps', node.id, `variants.${l}.json`), null); if (v) variants[l] = v }
+  const { node: out, index, file } = assembleStack({ node, base, environment: run.meta?.environment?.name || null, captures: list, attachments, rotation, variants, traffic })
   if (indexes) indexes.set(node.id, index); else await writeJson(join(run.dir, file), index)
   return out
 }

package/src/lib/capture.mjs

@@ -336,7 +336,7 @@ export async function captureStep ({ page, node, locale, viewports, run, console
         ...(unstable ? { unstable } : {}),
         ...(keyboard ? { keyboard } : {}),
         ...(details.length ? { details } : {}),
-        ...(item ? { item: { id: item.id, path: item.path, ...(item.title ? { title: item.title } : {}), ...(item.purpose ? { purpose: item.purpose } : {}), ...(item.edit_url ? { edit_url: item.edit_url } : {}), ...(item.content_ref ? { content_ref: item.content_ref } : {}), ...(item.last_checked !== undefined ? { last_checked: item.last_checked } : {}) } } : {}),
+        ...(item ? { item: { id: item.id, path: item.path, ...(item.source_path ? { source_path: item.source_path } : {}), ...(item.title ? { title: item.title } : {}), ...(item.purpose ? { purpose: item.purpose } : {}), ...(item.edit_url ? { edit_url: item.edit_url } : {}), ...(item.content_ref ? { content_ref: item.content_ref } : {}), ...(item.last_checked !== undefined ? { last_checked: item.last_checked } : {}) } } : {}),
         ...(fields ? { fields: { ...(await page.evaluate(readFields, fields).catch(() => ({}))), ...(fields.some((f) => (f.from || f.id) === 'http') ? Object.fromEntries(fields.filter((f) => (f.from || f.id) === 'http').map((f) => [f.id, extra.http_status ?? result.http_status ?? null])) : {}) } } : {}),
         files: { png: relative(run.dir, image), image: relative(run.dir, image), thumb: thumbWritten ? relative(run.dir, thumb) : null, html: relative(run.dir, html) }
       }

package/src/lib/findings.mjs

@@ -1,11 +1,16 @@
 // `kaloko export findings` (#160): the fix list of a run. Every failing acceptance criterion and health check, per
 // page and locale, with the evidence and the way back to the source (edit_url, content_ref of stack pages), as CSV for
 // a content team or JSON for an agent that feeds a content API. Stack steps are read page by page from their items
-// index; the viewports a check fails in are one row.
+// index; the viewports a check fails in are one row. With traffic data (#157) every row carries the page's numbers and
+// an impact score, and the list is sorted by it.
 import { healthOfNode, levelOf, isHealthCriterion } from './health-core.mjs'
 import { toCsv } from './evidence-core.mjs'
+import { VARIANT_CHECK } from './variants-core.mjs'
+import { impactOf, trafficView } from './traffic-core.mjs'
 
 export const FINDING_COLUMNS = ['step', 'page', 'locale', 'viewports', 'url', 'kind', 'pack', 'check', 'level', 'text', 'evidence', 'edit_url', 'content_ref', 'recheck']
+/** Columns the CSV adds when the run has traffic data. */
+export const TRAFFIC_COLUMNS = ['clicks', 'impressions', 'ctr', 'position', 'sessions', 'conversions', 'impact']
 
 const recheckOf = (step, locale, page) => `kaloko walk --steps ${step}${page ? ` --items ${page}` : ''}${locale ? ` --locales ${locale}` : ''}`
 
@@ -24,10 +29,12 @@ function collect (rows, base, results) {
 /**
  * The fix list of a manifest: [{ step, page, locale, viewports, url, kind (acceptance|health), pack, check, level
  * (error|warning for health, fail for acceptance), text, evidence, edit_url, content_ref, recheck }]. `stackIndex(node)`
- * returns a stack step's items index (qawalk.stack.v1). `locale` and `step` filter.
+ * returns a stack step's items index (qawalk.stack.v1). `locale` and `step` filter. `traffic` (traffic.mjs
+ * loadTraffic) adds `traffic` and `impact` to every row and sorts the list by impact, highest first.
  */
-export async function runFindings (manifest, { stackIndex, locale = null, step = null } = {}) {
+export async function runFindings (manifest, { stackIndex, locale = null, step = null, traffic = null } = {}) {
   const rows = []
+  const pageTraffic = new Map()
   for (const n of manifest?.nodes || []) {
     if (n.kind === 'decision' || (step && n.id !== step)) continue
     if (n.kind === 'stack' && n.stack?.items) {
@@ -45,8 +52,16 @@ export async function runFindings (manifest, { stackIndex, locale = null, step =
             results.push({ locale: l, viewport: vp, url: it.captures?.[l]?.[vp]?.url || it.url, check: id, kind: c.health ? 'health' : 'acceptance', pack: c.pack, level: c.health ? (c.level || levelOf(id)) : 'fail', text: c.text, evidence })
           }
         }
+        if (it.traffic) pageTraffic.set(`${n.id}|${it.id}`, it.traffic)
         collect(rows, { step: n.id, page: it.id, url: it.url, edit_url: it.edit_url || null, content_ref: it.content_ref || null }, results)
       }
+      // locale variants (#176): a page without its own version in a locale is a finding of that locale, at the source
+      // page, where the hreflang (or the translation) is missing
+      const byId = new Map((idx.items || []).map((it) => [it.id, it]))
+      for (const [l, v] of Object.entries(idx.variants?.locales || {})) {
+        if (v.source || (locale && l !== locale)) continue
+        for (const m of v.missing || []) { const it = byId.get(m.id); rows.push({ step: n.id, page: m.id, locale: l, viewports: [], url: m.url || it?.url || null, kind: 'health', pack: VARIANT_CHECK.pack, check: VARIANT_CHECK.id, level: 'warning', text: VARIANT_CHECK.text, evidence: m.reason || null, edit_url: it?.edit_url || null, content_ref: it?.content_ref || null, recheck: recheckOf(n.id, l, m.id) }) }
+      }
       continue
     }
     const checks = [...(n.criteria || []).filter((c) => !isHealthCriterion(c)).map((c) => ({ ...c, kind: 'acceptance' })), ...healthOfNode(n).list.map((c) => ({ ...c, kind: 'health' }))]
@@ -63,11 +78,21 @@ export async function runFindings (manifest, { stackIndex, locale = null, step =
     }
     collect(rows, { step: n.id, page: null, url: null, edit_url: null, content_ref: null }, results)
   }
-  return rows
+  if (!traffic?.table && !pageTraffic.size) return rows
+  // the page's own numbers in this language (its address), else what the stack index joined for the page; GA4 paths
+  // without a host only when the run walks one host
+  const hosts = new Set(rows.map((r) => { try { return new URL(r.url).host } catch { return null } }).filter(Boolean))
+  for (const r of rows) {
+    const t = trafficView((r.url && traffic?.table?.of(r.url, { paths: hosts.size <= 1 })) || pageTraffic.get(`${r.step}|${r.page}`) || null)
+    r.traffic = t; r.impact = impactOf(t, r.level)
+  }
+  return rows.map((r, i) => [r, i]).sort((a, b) => b[0].impact - a[0].impact || a[1] - b[1]).map(([r]) => r)
 }
 
 /** The fix list as CSV (one row per finding, viewports space-separated) or JSON ({ run, scenario, findings }). */
 export function findingsText (rows, format, { run = null, scenario = null } = {}) {
   if (format === 'json') return JSON.stringify({ schema: 'qawalk.findings.v1', run, scenario, count: rows.length, findings: rows }, null, 2)
-  return toCsv(rows.map((r) => ({ ...r, viewports: r.viewports.join(' ') })), FINDING_COLUMNS)
+  // traffic columns only when the run has traffic data, so the list of a run without it keeps its columns
+  const withTraffic = rows.some((r) => 'impact' in r)
+  return toCsv(rows.map((r) => ({ ...r, ...(r.traffic || {}), viewports: r.viewports.join(' ') })), withTraffic ? [...FINDING_COLUMNS, ...TRAFFIC_COLUMNS] : FINDING_COLUMNS)
 }