kaloko 0.18.0 → 0.20.0

package/skills/kaloko/reference/stacks.md

@@ -17,6 +17,18 @@ sorting, thumbnails and CSV export, and each page opens in the lightbox.
   per page, and export the failing ones for the content team.
 - A redesign or migration: walk the old URL list against the new site.
 
+For a weekly SEO and answer-engine monitor of a public site, start with
+`npx kaloko init --seo <site>`: it reads robots.txt and the sitemaps, finds
+the languages and the biggest content families and writes
+`qa/flows/seo-<site>.yml` with one rotating stack per family (`match` per
+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. 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
 step script only to prepare each page, for example to dismiss a dialog
@@ -31,10 +43,14 @@ step script only to prepare each page, for example to dismiss a dialog
   purpose: Every article reads well and is findable.
   packs: [seo]                              # health checks of every page (advisory)
   items:
-    sitemap: /sitemap.xml                   # or urls / file / crawl / script (exactly one)
+    sitemap: /sitemap.xml                   # or robots: true / urls / file / crawl / script (exactly one)
     match: '^/clanky/'                      # regex on the path with its query; exclude: '…' drops pages
+                                            # or a map by locale: { default: '^/blog/', fi: '^/fi/blogi/' }
     limit: 800                              # default 500, at most 10000
-    semantic_sample: 20                     # semantic criteria on the first 20 pages only
+    # 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
   fields:                                   # index columns (max 12); default title, h1, words, http
     - { id: title, label: Title, from: title }
@@ -55,12 +71,43 @@ Item sources:
 - `file: qa/data/products.csv` is a list next to the scenario. Accepted
   formats are text with one path per line, CSV (first column), or JSON:
   `["/a"]` or `[{ path, title, key, purpose }]`, where `key` gives a stable id.
-- `sitemap: /sitemap.xml` also follows a sitemap index (up to 50 sitemaps).
+- `sitemap: /sitemap.xml` also follows a sitemap index, two levels deep
+  (up to 50 sitemaps each). Gzipped sitemaps work: a `.gz` URL or gzip
+  bytes behind any URL are unpacked.
+- `sitemap: robots` (or `robots: true`) reads the `Sitemap:` lines of
+  `/robots.txt` on the environment's origin. When their URLs name the
+  walked locale as a segment (`/sitemaps/de/sitemap.xml.gz`,
+  `sitemap-de.xml`; `en_US` finds `en-us`, `en` does not), only that
+  locale's sitemaps are read; otherwise all of them. Use it when a site
+  lists one sitemap per language, so the scenario does not hard-code paths.
 - `crawl: { from: /clanky, links: "a.card", next: "a.next", pages: 20 }`
   collects links from a listing and follows its pagination.
 - `script: qa/steps/items.mjs` uses the default export
-  `({ page, env, locale, url }) => [paths | { path, title, key, purpose }]` for
-  anything else, such as an API or a search.
+  `({ page, env, locale, url, node, params }) => [paths | { path, title, key, purpose }]`
+  for anything else, such as an API or a search. `node` is
+  `{ id, title, lane, lane_title, session }` of the step and `params` is
+  `items.params`, so one script can serve several stacks.
+
+Fix handoff: a script or a JSON list may give each page `edit_url` (the
+page in the CMS, http(s) only) and `content_ref` (its record id for a
+content API). `resolve: steps/resolve.mjs` (default export
+`async (item, { env, locale, node, params, url }) => ({ edit_url, content_ref })`)
+looks them up for the walked pages only, 15 s per page; a page it fails on is walked
+without them and the walk says how many. They show in the page detail
+("Edit in CMS"), the stack CSV, `get_stack_items` and
+`kaloko export findings`.
+
+`match` and `exclude` apply to every source before `limit` (and before
+`rotate`). Either is a regex or a map by locale; the walked locale, then its
+language (`en` for `en_US`), then `default` is used. A `match` map without
+the locale and without `default` is an error.
+
+`rotate: week` (or `rotate: run`) walks a big list in turns: each ISO week
+(or each run) takes the next `limit` pages, wrapping around, so the list is
+covered in `pages ÷ limit` rounds. `run` keeps its count and each page's last
+check in `.cache/stack/` of the output folder, so use `week` on CI with a
+fresh checkout. The stack index gets `rotation` per locale (window, covered,
+never checked) and each page `last_checked` (its previous check, or null).
 
 An item's `purpose` (for example its title and meta description) is what the
 semantic evaluator reads as `screen_purpose` for that page instead of the
@@ -73,32 +120,144 @@ in the wrong language.
 Pages are deduplicated. External URLs are allowed (e.g. an old domain).
 `{locale}` in any source string is replaced by the walked locale. This is
 how one sitemap with every language is split:
-`match: '^/guides/.*lang={locale}'`, or `sitemap: /{locale}/sitemap.xml`.
+`match: '^/guides/.*lang={locale}'`, or `sitemap: /{locale}/sitemap.xml`,
+or `sitemap: /sitemaps/{locale}/sitemap.xml.gz`. One content family per
+stack: the same per-locale sitemap with `match: '/eshop/'` in one step and
+`match: '/(magazin|magazine|revista)/'` in another.
 
 Field sources: `title`, `h1`, `description`, `canonical`, `lang`, `url`,
 `path`, `words` (words in main/article/body), `http` (the navigation
-status), `count:<selector>`, `<selector>` (text) and `<selector>@<attr>`.
+status), `jsonld_types` (the schema.org types of the page's JSON-LD, for
+example `Product, Offer, BreadcrumbList`; `invalid×1` when a block does not
+parse), a meta tag by name (`og:title`, `og:image`, `twitter:card`,
+`meta:robots`), `count:<selector>`, `<selector>` (text) and
+`<selector>@<attr>`.
+
+Structured data is also summarised without a field: every capture records
+`structured_data` (blocks, invalid blocks, types), and `items.json` carries
+`structured_data` per page and, at the top, pages per type, pages without
+structured data and pages with invalid JSON-LD. The `seo` pack checks it
+(HC112 present, HC113 valid); `packs: [aeo]` adds the answer-engine signals
+(HC901–HC905; HC905 `nojs_parity` fetches each page's raw HTML as GPTBot,
+respecting robots.txt, and fails when the title, canonical, H1, JSON-LD or
+most of the text appear only after JavaScript). See
+help/reference/checks-and-packs.md.
+
+With the `seo` pack a stack also compares its pages with each other after the
+walk (HC121–HC126, advisory): shared titles, descriptions and H1s within a
+language, canonicals pointing elsewhere or to error/noindex pages, hreflang
+that the other walked version does not answer, and (sitemap or robots
+sources) listed pages that answer non-200, redirect or say noindex. They are
+health entries of the stack node (`cross_page: true`, `counts` in pages,
+`urls`); `items.json` has them under `cross_page` with the groups, and each
+affected page lists the ids in `cross_fails`. They cannot be adopted.
+`packs: [locale]` (scenarios with `locales`) checks html lang, the own
+hreflang, the text's language and price decimals against the walked locale
+(HC1001–HC1004). `health: { site: true }` on the scenario adds site checks
+once per run (robots.txt, sitemaps, llms.txt, http→https and www redirects;
+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.
-- Semantic criteria go to the evaluator. On a stack they run only on the
-  first `semantic_sample` pages (default 20). The other pages show the
-  criterion as not evaluated. Raise the sample only when the question
+- Semantic criteria go to the evaluator. On a stack they run only on
+  `semantic_sample` pages (default 20), the first in walk order. With
+  `semantic_order: priority`, or an evaluator budget, pages failing a
+  deterministic acceptance criterion come first, then those never or least
+  recently checked. The other pages show the criterion as not evaluated. `evaluate.budget.calls`
+  caps the calls of a whole evaluation (evaluation.md). Raise the sample only when the question
   really differs between pages, and tell the person what it costs
   (one call per page and viewport).
 - Stacks capture the first screen of each page (fast, small). Set
   `capture: { full_page: true }` when the criteria are about the whole page.
 - Walking takes about 1–2 s per page. For a first look, use
   `kaloko walk --limit 50`. Re-walk chosen pages with
-  `--items clanek-7,clanek-12` (matches the id or the path).
-- A shared run holds at most 20000 files and 300 MB. Each page stores about
-  four files, so a stack of a few thousand first-screen pages fits. Split
-  larger catalogues by section (`match`), one stack per section.
+  `--items clanek-7,clanek-12` (matches the id or the path; picked from
+  every matching page, also outside this week's rotation, and such a
+  partial walk leaves the rotation state alone).
+- A shared run holds at most 20000 files and 300 MB as stored (HTML and JSON
+  travel gzip-compressed, about a tenth of their size on disk). Each page
+  stores about four files, so a stack of a few thousand first-screen pages
+  fits. For SEO crawls where the checks read the page, not the picture, set
+  `capture: { screenshot: thumb }`: only the 640 px thumbnail is kept. Split
+  larger catalogues by section (`match`) or walk a rotating sample
+  (`rotate: week`).
 
 ## Reading the results
 
@@ -118,13 +277,19 @@ the walk opens each page and captures it.
   `get_stack_items {run_id, step, status?, criterion?, query?, offset, limit}`
   lists pages with fields, failing criteria, evidence and screenshot URLs.
   This is the way to hand an agent "fix these 37 articles".
+- `kaloko export findings [--format csv|json] [--locale l] [--step s] [--out file]`
+  writes the fix list of the local run: one row per failing criterion or
+  health check, page and locale, with URL, evidence, `edit_url`,
+  `content_ref` and `recheck` (`kaloko walk --steps s --items <page> --locales l`,
+  which re-walks just that page after the fix).
 
 ## Report
 
 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